@koobiq/components 20.4.2 → 21.0.1

package/schematics/utils/tag-patterns.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+// RegExp sources the template rewrites of v20-upgrade and v21-upgrade build on. They live here rather than in a
+// `data.ts`: v21-upgrade's `data.ts` imports every area module, so an area that read them from there would get
+// `undefined` under CommonJS.
+/**
+ * One step inside an opening tag: a quoted value is taken whole, so neither `>` nor an attribute-like word inside
+ * it counts.
+ */
+const TAG_BODY = `(?:[^<>"']|"[^"]*"|'[^']*')`;
+/**
+ * The start of an attribute on an opening `<kbq-code-block>` tag that does not bind `name` itself, captured as
+ * `$1` together with a `[` that opens a binding.
+ */
+const codeBlockTagWithout = (name) => String.raw `(<kbq-code-block(?![\w-])(?!${TAG_BODY}*[\s\[]${name}[\]\s=/>])${TAG_BODY}*?\s\[?)`;
+/** An opening `<kbq-code-block>` tag that binds both `first` and `second`. */
+const codeBlockTagWith = (first, second) => String.raw `<kbq-code-block(?![\w-])(?=${TAG_BODY}*[\s\[]${first}[\]\s=/>])(?=${TAG_BODY}*[\s\[]${second}[\]\s=/>])`;
+
+exports.TAG_BODY = TAG_BODY;
+exports.codeBlockTagWith = codeBlockTagWith;
+exports.codeBlockTagWithout = codeBlockTagWithout;

package/schematics/utils/template-ref-access.cjs

@@ -0,0 +1,155 @@
+'use strict';
+
+var utils_ast = require('./ast.cjs');
+var utils_signalMembersMigration = require('./signal-members-migration.cjs');
+require('typescript');
+require('./messages.cjs');
+require('./package-config.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('./project-files.cjs');
+require('./typescript.cjs');
+
+/** A compound assignment (`+=`, `??=`, …) or a postfix `++` / `--` at the start of what follows an access. */
+const COMPOUND_WRITE_AFTER = /^\s*(?:\+\+|--|(?:\*\*|>>>|<<|>>|&&|\|\||\?\?|[-+*/%&|^])=(?!=))/;
+/** A prefix `++` / `--` at the end of what precedes an access. */
+const INCREMENT_BEFORE = /(?:\+\+|--)\s*$/;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** `<ref>.<member> =`, but not `==` / `===`: the lookbehind matches the one `memberAccessPattern` uses. */
+function assignmentPattern(ref, members) {
+    const names = members.map(escapeRegExp).join('|');
+    return new RegExp(`(?<![\\w$.])(${escapeRegExp(ref)}\\s*\\.\\s*(${names}))\\b(\\s*=(?!=)\\s*)`, 'g');
+}
+/** `<ref>.<member>` in any form, the optional chain included. */
+function anyAccessPattern(ref, members) {
+    return new RegExp(`(?<![\\w$.])${escapeRegExp(ref)}\\s*\\??\\.\\s*(${members.map(escapeRegExp).join('|')})\\b`, 'g');
+}
+/** End of the assigned expression that starts at `from`: the next top-level `;`, or the end of the statement list. */
+function assignedExpressionEnd(template, from, limit) {
+    let depth = 0;
+    let quote;
+    let end = limit;
+    for (let i = from; i < limit && end === limit; i++) {
+        const char = template[i];
+        if (quote) {
+            if (char === '\\')
+                i++;
+            else if (char === quote)
+                quote = undefined;
+        }
+        else if (char === "'" || char === '"' || char === '`') {
+            quote = char;
+        }
+        else if ('([{'.includes(char)) {
+            depth++;
+        }
+        else if (')]}'.includes(char)) {
+            if (depth === 0)
+                end = i;
+            else
+                depth--;
+        }
+        else if (char === ';' && depth === 0) {
+            end = i;
+        }
+    }
+    while (end > from && /\s/.test(template[end - 1]))
+        end--;
+    return end;
+}
+/**
+ * Rewrites reads and writes of the members reachable through the refs in `template`, whose HTML AST is
+ * `rootNodes`. `policyOf` tells what a `#ref` on an element is bound to, or `undefined` when it is not one of
+ * the migrated types.
+ */
+function rewriteRefAccesses(template, rootNodes, policyOf) {
+    const scanner = new utils_signalMembersMigration.TemplateScanner(template, policyOf);
+    const result = {
+        content: template,
+        readOnlyWrites: new Set(),
+        compoundWrites: new Set(),
+        reported: new Set()
+    };
+    const writeEdits = [];
+    const readEdits = [];
+    // The end of each access already handled: a ref redeclared in a nested view reaches it twice.
+    const seen = new Set();
+    utils_ast.visitAll(scanner, rootNodes);
+    const rewriteWrites = (expression, name, policy) => {
+        const source = template.slice(expression.start, expression.end);
+        for (const match of source.matchAll(assignmentPattern(name, policy.members))) {
+            const [, target, member, operator] = match;
+            const targetEnd = expression.start + match.index + target.length;
+            if (seen.has(targetEnd))
+                continue;
+            seen.add(targetEnd);
+            if (!policy.writable.has(member)) {
+                result.readOnlyWrites.add(member);
+                continue;
+            }
+            // Outside a statement an assignment is no valid template to begin with.
+            if (expression.kind !== 'statement')
+                continue;
+            const valueStart = targetEnd + operator.length;
+            const valueEnd = assignedExpressionEnd(template, valueStart, expression.end);
+            if (valueEnd === valueStart)
+                continue;
+            writeEdits.push({ start: targetEnd, end: valueStart, text: '.set(' });
+            writeEdits.push({ start: valueEnd, end: valueEnd, text: ')' });
+        }
+    };
+    const rewriteReads = (expression, name, policy) => {
+        const source = template.slice(expression.start, expression.end);
+        for (const match of source.matchAll(utils_signalMembersMigration.memberAccessPattern(name, policy.members))) {
+            const start = expression.start + match.index;
+            const end = start + match[0].length;
+            const member = match[2];
+            if (seen.has(end))
+                continue;
+            seen.add(end);
+            // `(click)="ref.value += 1"`, `ref.value++`, `--ref.value`: a call there is no valid template.
+            if (expression.kind === 'statement' &&
+                (COMPOUND_WRITE_AFTER.test(template.slice(end, expression.end)) ||
+                    INCREMENT_BEFORE.test(template.slice(expression.start, start)))) {
+                (policy.writable.has(member) ? result.compoundWrites : result.readOnlyWrites).add(member);
+                continue;
+            }
+            // `[(ngModel)]="ref.value"` writes through the binding: a writable signal fills it as it is.
+            if (expression.kind === 'twoWay' &&
+                !template.slice(expression.start, start).trim() &&
+                !template.slice(end, expression.end).trim()) {
+                if (!policy.writable.has(member))
+                    result.readOnlyWrites.add(member);
+                continue;
+            }
+            readEdits.push({ start: end, end, text: '()' });
+        }
+    };
+    for (const { name, type: policy, ...view } of scanner.unambiguousRefs()) {
+        for (const expression of scanner.expressions) {
+            if (expression.start < view.start || expression.end > view.end)
+                continue;
+            if (policy.members.length > 0) {
+                rewriteWrites(expression, name, policy);
+                rewriteReads(expression, name, policy);
+            }
+            if (policy.reported?.length) {
+                const source = template.slice(expression.start, expression.end);
+                for (const [, member] of source.matchAll(anyAccessPattern(name, policy.reported))) {
+                    result.reported.add(member);
+                }
+            }
+        }
+    }
+    // Applied right to left. The sort is stable, so where a read ends an assigned value, the `)` closing
+    // `.set(` goes in first and the read's `()` lands in front of it.
+    const edits = [...writeEdits, ...readEdits].sort((a, b) => b.start - a.start || b.end - a.end);
+    for (const { start, end, text } of edits) {
+        result.content = result.content.slice(0, start) + text + result.content.slice(end);
+    }
+    return result;
+}
+
+exports.rewriteRefAccesses = rewriteRefAccesses;

package/schematics/utils/{typescript.js → typescript.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 var ts = require('typescript');
-var utils_ast = require('./ast.js');
+var utils_ast = require('./ast.cjs');
 
 const LEADING_TRIVIA_CHARS = [' ', '\n', '\r', '\t'];
 function forEachClass(sourceFile, callback) {

package/schematics/utils/warn-only-migration.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+var utils_messages = require('./messages.cjs');
+var utils_packageConfig = require('./package-config.cjs');
+var utils_projectFiles = require('./project-files.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+/**
+ * Builds the rule of a migration that only reports: every `.ts` file of the project that matches a pattern is
+ * logged with its message, then the summary. Never writes.
+ *
+ * The patterns are compiled once here rather than per file. None carries the `g` flag, so a shared instance
+ * holds no `lastIndex`.
+ */
+function warnOnlyRule(config, options) {
+    const { label, summary } = config;
+    const warnPatterns = config.warnPatterns.map(({ anchor, pattern, message }) => ({
+        anchor: anchor ? new RegExp(anchor) : null,
+        pattern: new RegExp(pattern),
+        message
+    }));
+    return async (tree, context) => {
+        const projectDefinition = await utils_packageConfig.setupOptions(options.project, tree);
+        const root = projectDefinition?.root ?? '';
+        let reported = 0;
+        utils_projectFiles.visitProjectFiles(root ? tree.getDir(root) : tree.root, (filePath, entry) => {
+            if (!filePath.endsWith('.ts'))
+                return;
+            const content = entry.content.toString();
+            if (!content)
+                return;
+            for (const { anchor, pattern, message } of warnPatterns) {
+                if (anchor && !anchor.test(content))
+                    continue;
+                if (!pattern.test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${label} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here is affected, so the summary would only be noise.
+        if (reported === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${label} processed "${root || '<workspace root>'}", ${reported} use(s) reported.`,
+            ...summary
+        ]);
+    };
+}
+
+exports.warnOnlyRule = warnOnlyRule;

package/schematics/utils/workspace-styles.cjs

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * 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;
+}
+
+exports.applyKoobiqWorkspaceStyles = applyKoobiqWorkspaceStyles;
+exports.getIndexHtmlPath = getIndexHtmlPath;
+exports.getKoobiqStyleEntries = getKoobiqStyleEntries;
+exports.mergeKoobiqStyles = mergeKoobiqStyles;

package/scrollbar/{_scrollbar-component-theme.scss → deprecated/_scrollbar-component-theme.scss}

@@ -1,4 +1,4 @@
-@use '../core/styles/common/tokens' as *;
+@use '../../core/styles/common/tokens' as *;
 
 @mixin kbq-scrollbar-component-theme() {
     .kbq-scrollbar-component {

package/scrollbar/{scrollbar.component.scss → deprecated/scrollbar.component.scss}

@@ -1,4 +1,4 @@
-@use '../core/styles/common/tokens' as *;
+@use '../../core/styles/common/tokens' as *;
 @use './scrollbar-component-theme' as *;
 
 .kbq-scrollbar-component {

package/scrollbar/native-scrollbar.scss

@@ -0,0 +1,68 @@
+/* stylelint-disable selector-pseudo-class-no-unknown */
+
+// `scrollbar-color` is inherited. Reset it on descendants unless the directive explicitly opts into
+// styling them; the zero-specificity selector lets a descendant's own scrollbar styles override this.
+@supports not selector(::-webkit-scrollbar) {
+    :where(.kbq-native-scrollbar:not(.kbq-native-scrollbar_descendants) *) {
+        scrollbar-color: auto;
+    }
+
+    .kbq-native-scrollbar,
+    .kbq-native-scrollbar_descendants * {
+        scrollbar-color: var(--kbq-scrollbar-thumb-default-background) var(--kbq-scrollbar-track-background);
+        // The standardized API only supports `auto`, `thin`, and `none`, so an exact token-based size
+        // is available only through the WebKit pseudo-elements below.
+        scrollbar-width: auto;
+    }
+}
+
+.kbq-native-scrollbar::-webkit-scrollbar,
+.kbq-native-scrollbar_descendants ::-webkit-scrollbar {
+    width: var(--kbq-scrollbar-track-size);
+    height: var(--kbq-scrollbar-track-size);
+    background-color: var(--kbq-scrollbar-track-background);
+    cursor: default;
+}
+
+.kbq-native-scrollbar::-webkit-scrollbar-track,
+.kbq-native-scrollbar::-webkit-scrollbar-corner,
+.kbq-native-scrollbar::-webkit-resizer,
+.kbq-native-scrollbar_descendants ::-webkit-scrollbar-track,
+.kbq-native-scrollbar_descendants ::-webkit-scrollbar-corner,
+.kbq-native-scrollbar_descendants ::-webkit-resizer {
+    background-color: var(--kbq-scrollbar-track-background);
+}
+
+.kbq-native-scrollbar::-webkit-scrollbar-thumb,
+.kbq-native-scrollbar_descendants ::-webkit-scrollbar-thumb {
+    box-sizing: border-box;
+    border: var(--kbq-scrollbar-thumb-gap) solid transparent;
+    border-radius: var(--kbq-size-border-radius);
+    background-color: var(--kbq-scrollbar-thumb-default-background);
+    background-clip: content-box;
+}
+
+.kbq-native-scrollbar::-webkit-scrollbar-thumb:vertical,
+.kbq-native-scrollbar_descendants ::-webkit-scrollbar-thumb:vertical {
+    min-height: calc(var(--kbq-scrollbar-thumb-min-size) + var(--kbq-scrollbar-thumb-gap) * 2);
+}
+
+.kbq-native-scrollbar::-webkit-scrollbar-thumb:horizontal,
+.kbq-native-scrollbar_descendants ::-webkit-scrollbar-thumb:horizontal {
+    min-width: calc(var(--kbq-scrollbar-thumb-min-size) + var(--kbq-scrollbar-thumb-gap) * 2);
+}
+
+.kbq-native-scrollbar::-webkit-scrollbar-thumb:hover,
+.kbq-native-scrollbar_descendants ::-webkit-scrollbar-thumb:hover {
+    background-color: var(--kbq-scrollbar-thumb-hover-background);
+}
+
+.kbq-native-scrollbar::-webkit-scrollbar-thumb:active,
+.kbq-native-scrollbar_descendants ::-webkit-scrollbar-thumb:active {
+    background-color: var(--kbq-scrollbar-thumb-active-background);
+}
+
+.kbq-native-scrollbar::-webkit-scrollbar-button,
+.kbq-native-scrollbar_descendants ::-webkit-scrollbar-button {
+    display: none;
+}

package/scrollbar/scrollbar-tokens.scss

@@ -1,25 +1,16 @@
-:where(.kbq-scrollbar-component) {
-    --kbq-scrollbar-size-track-dimension: var(--kbq-size-l);
-    --kbq-scrollbar-size-track-padding-vertical: var(--kbq-size-3xs);
-    --kbq-scrollbar-size-track-padding-horizontal: var(--kbq-size-3xs);
-    --kbq-scrollbar-size-thumb-width: var(--kbq-size-s);
-    --kbq-scrollbar-size-thumb-min-size: var(--kbq-size-xl);
-    --kbq-scrollbar-size-thumb-border-radius: var(--kbq-size-s);
-    /* THEME TOKENS */
-    --kbq-scrollbar-thumb-default-background: var(--kbq-semantic-contrast-a3, var(--kbq-palette-grey-50-a32));
-    --kbq-scrollbar-thumb-hover-background: var(--kbq-semantic-contrast-a4, var(--kbq-palette-grey-50-a48));
-    --kbq-scrollbar-thumb-active-background: var(--kbq-semantic-contrast-a5, var(--kbq-palette-grey-20-a55));
-    --kbq-scrollbar-thumb-disabled-background: var(--kbq-states-icon-disabled);
-    --kbq-scrollbar-track-default-border: transparent;
-    --kbq-scrollbar-track-default-background: transparent;
-    --kbq-scrollbar-track-hover-border: transparent;
-    --kbq-scrollbar-track-hover-background: transparent;
-    --kbq-scrollbar-track-active-border: transparent;
-    --kbq-scrollbar-track-active-background: transparent;
+:where(.kbq-scrollbar-viewport, .kbq-native-scrollbar) {
+    --kbq-scrollbar-thumb-min-size: var(--kbq-size-3xl);
+    --kbq-scrollbar-thumb-gap: 3px;
+    --kbq-scrollbar-track-size: 14px;
+    // Above any content inside the viewport. Safe as an absolute value because the viewport isolates it —
+    // it never competes with page-level layers such as the navbar or overlays.
+    --kbq-scrollbar-track-z-index: 1000;
+    --kbq-scrollbar-transition-duration: 0.15s;
+    --kbq-scrollbar-track-background: transparent;
 }
 
-:where(.kbq-dark .kbq-scrollbar-component) {
-    --kbq-scrollbar-thumb-default-background: var(--kbq-semantic-dark-contrast-a9, var(--kbq-palette-grey-50-a48));
-    --kbq-scrollbar-thumb-hover-background: var(--kbq-semantic-dark-contrast-a10, var(--kbq-palette-grey-50-a60));
-    --kbq-scrollbar-thumb-active-background: var(--kbq-semantic-dark-contrast-a11, var(--kbq-palette-grey-50-a80));
+@media (prefers-reduced-motion: reduce) {
+    :where(.kbq-scrollbar-viewport, .kbq-native-scrollbar) {
+        --kbq-scrollbar-transition-duration: 0s;
+    }
 }

package/scrollbar/scrollbar-track.scss

@@ -0,0 +1,94 @@
+@use '../core/styles/common/animation';
+
+:host {
+    position: sticky;
+    z-index: var(--kbq-scrollbar-track-z-index, 1000);
+    display: block;
+    // Prevent a flex viewport from shrinking the track to zero; runtime margins cancel its layout contribution.
+    flex-shrink: 0;
+    pointer-events: none;
+    overflow: hidden;
+    // Inherit instance-level custom properties from the viewport that creates this element dynamically.
+    color: var(--kbq-scrollbar-color, currentColor);
+}
+
+@keyframes kbq-scrollbar-fade {
+    from {
+        opacity: 0;
+    }
+
+    to {
+        opacity: 1;
+    }
+}
+
+.kbq-scrollbar-track__bar {
+    position: absolute;
+    inset-inline-end: 0;
+    background: var(--kbq-scrollbar-track-background, transparent);
+    pointer-events: auto;
+}
+
+.kbq-scrollbar-track__bar_enter,
+.kbq-scrollbar-track__bar_leave {
+    animation: kbq-scrollbar-fade var(--kbq-scrollbar-transition-duration) ease-in-out;
+
+    @include animation.kbq-animations-off();
+}
+
+.kbq-scrollbar-track__bar_leave {
+    animation-direction: reverse;
+}
+
+.kbq-scrollbar-track__bar_vertical {
+    inset-block: 0;
+    inline-size: var(--kbq-scrollbar-track-size);
+}
+
+.kbq-scrollbar-track__bar_horizontal {
+    inset-block-end: 0;
+    inset-inline-start: 0;
+    block-size: var(--kbq-scrollbar-track-size);
+}
+
+.kbq-scrollbar-track__bar_has-horizontal {
+    inset-block-end: var(--kbq-scrollbar-track-size);
+}
+
+.kbq-scrollbar-track__bar_has-vertical {
+    inset-inline-end: var(--kbq-scrollbar-track-size);
+}
+
+.kbq-scrollbar-track__thumb {
+    transition: background-color var(--kbq-scrollbar-transition-duration) ease;
+    position: absolute;
+    // A transparent border keeps the painted thumb smaller than its hit area.
+    border: var(--kbq-scrollbar-thumb-gap) solid transparent;
+    border-radius: var(--kbq-size-border-radius);
+    box-sizing: border-box;
+    background-color: var(--kbq-scrollbar-thumb-default-background);
+    background-clip: content-box;
+    cursor: default;
+    user-select: none;
+    pointer-events: auto;
+
+    @include animation.kbq-animations-off();
+}
+
+.kbq-scrollbar-track__thumb:hover {
+    background-color: var(--kbq-scrollbar-thumb-hover-background);
+}
+
+.kbq-scrollbar-track__thumb:active {
+    background-color: var(--kbq-scrollbar-thumb-active-background);
+}
+
+.kbq-scrollbar-track__bar_vertical .kbq-scrollbar-track__thumb {
+    inset-inline: 0;
+    min-block-size: calc(var(--kbq-scrollbar-thumb-min-size) + var(--kbq-scrollbar-thumb-gap) * 2);
+}
+
+.kbq-scrollbar-track__bar_horizontal .kbq-scrollbar-track__thumb {
+    inset-block: 0;
+    min-inline-size: calc(var(--kbq-scrollbar-thumb-min-size) + var(--kbq-scrollbar-thumb-gap) * 2);
+}

package/scrollbar/scrollbar-viewport.scss

@@ -0,0 +1,33 @@
+@use '../core/styles/common/animation';
+
+// Confines the track's z-index to this element, mirroring how an OS draws its scrollbar as a sibling of
+// the scrolled content rather than a peer competing with it. Without this the track would either lose to
+// positioned content inside the viewport, or — once raised above it — leak past page-level layers.
+.kbq-scrollbar-viewport {
+    isolation: isolate;
+}
+
+.kbq-scrollbar-viewport_native-scrollbar-hidden {
+    scrollbar-width: none;
+    -ms-overflow-style: none;
+}
+
+.kbq-scrollbar-viewport_native-scrollbar-hidden::-webkit-scrollbar,
+.kbq-scrollbar-viewport_native-scrollbar-hidden::-webkit-scrollbar-thumb {
+    display: none;
+}
+
+.kbq-scrollbar-track_hover:not(:active) {
+    transition: opacity var(--kbq-scrollbar-transition-duration) ease;
+    opacity: 0;
+
+    @include animation.kbq-animations-off();
+}
+
+.kbq-scrollbar-viewport:hover > .kbq-scrollbar-track_hover,
+.kbq-scrollbar-track_hover.kbq-scrollbar-track_revealed {
+    transition: opacity var(--kbq-scrollbar-transition-duration) ease;
+    opacity: 1;
+
+    @include animation.kbq-animations-off();
+}

package/scrollbar/scrollbar.scss

@@ -0,0 +1,24 @@
+:host {
+    position: relative;
+    display: flex;
+    // Lets the host fill available space along whichever axis is the parent's main axis
+    // (cross-axis sizing is already handled by the parent's default `align-items: stretch`),
+    // so it behaves like a block element regardless of the parent's layout mode.
+    flex: 1;
+    min-inline-size: 0;
+    min-block-size: 0;
+    max-block-size: 100%;
+    isolation: isolate;
+    overflow: auto;
+}
+
+.kbq-scrollbar__content {
+    isolation: isolate;
+    flex: 1;
+    flex-basis: auto;
+    inline-size: 100%;
+    // A hard 100% (not `min-block-size`) so a `height: 100%` chain inside projected content (e.g. a
+    // grid that needs a definite pixel height to render at all) resolves correctly — content taller
+    // than the host still overflows past it normally and is measured via `scrollHeight` regardless.
+    block-size: 100%;
+}

package/search-expandable/search-expandable-tokens.scss

@@ -0,0 +1,4 @@
+:where(.kbq-search-expandable) {
+    --kbq-search-expandable-close-button-size: var(--kbq-size-xxl);
+    --kbq-search-expandable-close-button-border-radius: var(--kbq-size-xxs);
+}

package/search-expandable/search-expandable.scss

@@ -1,3 +1,5 @@
+@use '../core/styles/common/squircle' as *;
+
 .kbq-search-expandable {
     display: flex;
     flex-flow: row nowrap;
@@ -14,8 +16,8 @@
         align-items: center;
         justify-content: center;
 
-        border-radius: var(--kbq-size-xxs);
+        @include kbq-squircle(var(--kbq-search-expandable-close-button-border-radius));
 
-        height: var(--kbq-size-xxl);
+        height: var(--kbq-search-expandable-close-button-size);
     }
 }