@malva-ui/core 0.1.12

package/schematics/ng-add/index.cjs

@@ -0,0 +1,272 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.default = installMalvaUi;
+
+const { chain, SchematicsException } = require('@angular-devkit/schematics');
+const {
+  addDependency,
+  addRootProvider,
+  ExistingBehavior,
+  InstallBehavior,
+  readWorkspace,
+  updateWorkspace,
+} = require('@schematics/angular/utility');
+const packageJson = require('../../package.json');
+
+const GLOBAL_STYLESHEET = 'node_modules/@malva-ui/core/styles/malva-ui.css';
+
+/**
+ * Install and configure Malva UI in an Angular application.
+ *
+ * @param {{
+ *   project?: string;
+ *   theme?: "light" | "dark";
+ *   density?: "tight" | "compact" | "comfortable" | "spacious" | "airy";
+ *   includeStyles?: boolean;
+ *   configureProviders?: boolean;
+ *   themeStorageKey?: string;
+ *   skipInstall?: boolean;
+ * }} options Schematic options supplied by the Angular CLI.
+ * @returns {import("@angular-devkit/schematics").Rule} The installation rule.
+ */
+function installMalvaUi(options) {
+  return async (tree, context) => {
+    const workspace = await readWorkspace(tree);
+    const projectName = resolveApplicationProject(workspace, options.project);
+    const project = workspace.projects.get(projectName);
+
+    if (!project) {
+      throw new SchematicsException(
+        `Could not find the Angular project "${projectName}".`,
+      );
+    }
+
+    const normalizedOptions = {
+      theme: options.theme ?? 'light',
+      density: options.density ?? 'comfortable',
+      includeStyles: options.includeStyles ?? true,
+      configureProviders: options.configureProviders ?? true,
+      themeStorageKey: options.themeStorageKey ?? 'mlv-theme',
+      skipInstall: options.skipInstall ?? false,
+    };
+
+    context.logger.info(`\nInstalling Malva UI in "${projectName}"`);
+
+    const rules = [
+      logStep(1, 'Adding Malva UI companion packages'),
+      ...addCompanionDependencies(normalizedOptions.skipInstall),
+    ];
+
+    if (normalizedOptions.includeStyles) {
+      rules.push(
+        logStep(2, 'Adding Malva UI global styles'),
+        addGlobalStyles(projectName),
+      );
+    } else {
+      rules.push(logStep(2, 'Leaving global styles unchanged'));
+    }
+
+    if (normalizedOptions.configureProviders) {
+      rules.push(
+        logStep(3, 'Configuring theme and density providers'),
+        addProviderUnlessPresent(
+          projectName,
+          project.sourceRoot ?? `${project.root}/src`,
+          'provideDefaultTheme',
+          ({ code, external }) =>
+            code`${external(
+              'provideDefaultTheme',
+              '@malva-ui/core/layout',
+            )}(${JSON.stringify(normalizedOptions.theme)}, ${JSON.stringify(
+              normalizedOptions.themeStorageKey,
+            )})`,
+        ),
+        addProviderUnlessPresent(
+          projectName,
+          project.sourceRoot ?? `${project.root}/src`,
+          'provideMlvDensity',
+          ({ code, external }) =>
+            code`${external(
+              'provideMlvDensity',
+              '@malva-ui/cdk/density',
+            )}(${JSON.stringify(normalizedOptions.density)})`,
+        ),
+      );
+    } else {
+      rules.push(logStep(3, 'Leaving application providers unchanged'));
+    }
+
+    rules.push((resultTree, resultContext) => {
+      resultContext.logger.info(
+        '\nMalva UI is ready. Import components from @malva-ui/core/<component>.\n',
+      );
+      return resultTree;
+    });
+
+    return chain(rules);
+  };
+}
+
+/**
+ * Resolve a single application from the workspace or validate an explicit name.
+ *
+ * @param {import("@angular-devkit/core").workspaces.WorkspaceDefinition} workspace Angular workspace definition.
+ * @param {string | undefined} requestedProject Explicit project option.
+ * @returns {string} The resolved application name.
+ */
+function resolveApplicationProject(workspace, requestedProject) {
+  if (requestedProject) {
+    const requested = workspace.projects.get(requestedProject);
+
+    if (!requested) {
+      throw new SchematicsException(
+        `Project "${requestedProject}" does not exist in this workspace.`,
+      );
+    }
+
+    if (requested.extensions['projectType'] !== 'application') {
+      throw new SchematicsException(
+        `Project "${requestedProject}" is not an Angular application.`,
+      );
+    }
+
+    return requestedProject;
+  }
+
+  const applications = [];
+  for (const [name, project] of workspace.projects) {
+    if (project.extensions['projectType'] === 'application') {
+      applications.push(name);
+    }
+  }
+
+  if (applications.length === 1) {
+    return applications[0];
+  }
+
+  if (applications.length === 0) {
+    throw new SchematicsException(
+      'No Angular application was found in this workspace.',
+    );
+  }
+
+  throw new SchematicsException(
+    `This workspace contains multiple Angular applications (${applications.join(
+      ', ',
+    )}). Run the installer again with --project <name>.`,
+  );
+}
+
+/**
+ * Add the packages that back the grouped core distribution.
+ *
+ * @param {boolean} skipInstall Whether to suppress the package-manager task.
+ * @returns {import("@angular-devkit/schematics").Rule[]} Dependency rules.
+ */
+function addCompanionDependencies(skipInstall) {
+  const install = skipInstall ? InstallBehavior.None : InstallBehavior.Auto;
+  const dependencyOptions = {
+    existing: ExistingBehavior.Skip,
+    install,
+  };
+
+  return [
+    addDependency('@malva-ui/core', packageJson.version, dependencyOptions),
+    addDependency('@malva-ui/cdk', packageJson.version, dependencyOptions),
+    addDependency('@malva-ui/i18n', packageJson.version, dependencyOptions),
+  ];
+}
+
+/**
+ * Add the packaged Malva UI stylesheet to an application's build target.
+ *
+ * @param {string} projectName Application project name.
+ * @returns {import("@angular-devkit/schematics").Rule} Workspace update rule.
+ */
+function addGlobalStyles(projectName) {
+  return updateWorkspace((workspace) => {
+    const project = workspace.projects.get(projectName);
+    const buildTarget = project?.targets.get('build');
+
+    if (!project || !buildTarget) {
+      throw new SchematicsException(
+        `Could not find a build target for project "${projectName}".`,
+      );
+    }
+
+    const styles = buildTarget.options['styles'];
+    if (styles === undefined) {
+      buildTarget.options['styles'] = [GLOBAL_STYLESHEET];
+      return;
+    }
+
+    if (!Array.isArray(styles)) {
+      throw new SchematicsException(
+        `The build styles option for "${projectName}" is not an array and cannot be updated safely.`,
+      );
+    }
+
+    const alreadyConfigured = styles.some((style) =>
+      typeof style === 'string'
+        ? style === GLOBAL_STYLESHEET
+        : style && style['input'] === GLOBAL_STYLESHEET,
+    );
+
+    if (!alreadyConfigured) {
+      styles.push(GLOBAL_STYLESHEET);
+    }
+  });
+}
+
+/**
+ * Add a root provider only when the application's source does not already call it.
+ *
+ * @param {string} projectName Application project name.
+ * @param {string} sourceRoot Application source root.
+ * @param {string} providerName Provider function name used for idempotence.
+ * @param {import("@schematics/angular/utility").CodeBlockCallback} callback Provider code callback.
+ * @returns {import("@angular-devkit/schematics").Rule} Guarded provider rule.
+ */
+function addProviderUnlessPresent(
+  projectName,
+  sourceRoot,
+  providerName,
+  callback,
+) {
+  return (tree, context) => {
+    const normalizedRoot = `/${sourceRoot.replace(/^\/+|\/+$/g, '')}/`;
+    let isPresent = false;
+    tree.visit((filePath) => {
+      if (
+        !isPresent &&
+        filePath.startsWith(normalizedRoot) &&
+        filePath.endsWith('.ts') &&
+        tree.readText(filePath).includes(`${providerName}(`)
+      ) {
+        isPresent = true;
+      }
+    });
+
+    if (isPresent) {
+      context.logger.info(`  ${providerName} is already configured; skipping.`);
+      return tree;
+    }
+
+    return addRootProvider(projectName, callback)(tree, context);
+  };
+}
+
+/**
+ * Create a numbered progress message rule.
+ *
+ * @param {number} number Step number.
+ * @param {string} message Step description.
+ * @returns {import("@angular-devkit/schematics").Rule} Logging rule.
+ */
+function logStep(number, message) {
+  return (tree, context) => {
+    context.logger.info(`[${number}/3] ${message}`);
+    return tree;
+  };
+}

package/schematics/ng-add/schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "malva-ui-core-ng-add",
+  "title": "Malva UI installation",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The Angular application to configure.",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "theme": {
+      "type": "string",
+      "description": "The initial Malva UI color theme.",
+      "enum": ["light", "dark"],
+      "default": "light",
+      "x-prompt": {
+        "message": "Which color theme should Malva UI use initially?",
+        "type": "list",
+        "items": [
+          {
+            "value": "light",
+            "label": "Light"
+          },
+          {
+            "value": "dark",
+            "label": "Dark"
+          }
+        ]
+      }
+    },
+    "density": {
+      "type": "string",
+      "description": "The initial global component density.",
+      "enum": ["tight", "compact", "comfortable", "spacious", "airy"],
+      "default": "comfortable",
+      "x-prompt": {
+        "message": "Which component density should Malva UI use initially?",
+        "type": "list",
+        "items": [
+          {
+            "value": "comfortable",
+            "label": "Comfortable (recommended)"
+          },
+          {
+            "value": "compact",
+            "label": "Compact"
+          },
+          {
+            "value": "tight",
+            "label": "Tight"
+          },
+          {
+            "value": "spacious",
+            "label": "Spacious"
+          },
+          {
+            "value": "airy",
+            "label": "Airy"
+          }
+        ]
+      }
+    },
+    "includeStyles": {
+      "type": "boolean",
+      "description": "Add the Malva UI token, reset, and animation stylesheet to the application build.",
+      "default": true,
+      "x-prompt": "Add Malva UI global styles to the application build?"
+    },
+    "configureProviders": {
+      "type": "boolean",
+      "description": "Add the theme and density providers to the application bootstrap configuration.",
+      "default": true,
+      "x-prompt": "Configure the Malva UI theme and density providers?"
+    },
+    "themeStorageKey": {
+      "type": "string",
+      "description": "The browser storage key used to persist the selected theme.",
+      "default": "mlv-theme"
+    },
+    "skipInstall": {
+      "type": "boolean",
+      "description": "Skip installing companion package dependencies after configuration.",
+      "default": false,
+      "alias": "skip-install",
+      "visible": false
+    }
+  },
+  "additionalProperties": false
+}

package/scrollbar/index.d.ts

@@ -0,0 +1 @@
+export * from './lib/scrollbar/scrollbar';

package/scrollbar/lib/scrollbar/scrollbar.d.ts

@@ -0,0 +1,166 @@
+import type { BooleanInput } from '@angular/cdk/coercion';
+import * as i0 from "@angular/core";
+/** Controls which scroll axes render a custom scrollbar. */
+export type MlvScrollbarOrientation = 'vertical' | 'horizontal' | 'both';
+/**
+ * Custom scrollbar component that hides the native browser scrollbar and
+ * renders a minimalistic custom one in accordance with the Malva UI theme.
+ *
+ * Wrap any scrollable content in `<mlv-scrollbar>`. The component must have
+ * a defined height (set via CSS or via flex/grid sizing from a parent).
+ * Native scroll behaviour is **never intercepted** — the viewport scrolls
+ * exactly as if the component were not present. The custom thumb is a pure
+ * visual overlay that stays in sync with the viewport's scroll position.
+ *
+ * @example Vertical (default)
+ * ```html
+ * <mlv-scrollbar style="height: 12rem">
+ *   <p>Long content…</p>
+ * </mlv-scrollbar>
+ * ```
+ *
+ * @example Horizontal
+ * ```html
+ * <mlv-scrollbar orientation="horizontal" style="width: 20rem">
+ *   <div style="width: 60rem">Wide content…</div>
+ * </mlv-scrollbar>
+ * ```
+ *
+ * @example Both axes
+ * ```html
+ * <mlv-scrollbar orientation="both" style="height: 12rem; width: 20rem">
+ *   <div style="height: 30rem; width: 60rem">…</div>
+ * </mlv-scrollbar>
+ * ```
+ */
+export declare class MlvScrollbar {
+    /**
+     * Which scroll axes to show the custom scrollbar on.
+     * Default: `'vertical'`.
+     */
+    readonly orientation: import("@angular/core").InputSignal<MlvScrollbarOrientation>;
+    /**
+     * CSS length value for the scrollbar track zone width (vertical) or height
+     * (horizontal). Maps to the `--mlv-sb-size` custom property on the host.
+     * The visible thumb is narrower due to the cross-axis inset (`--mlv-sb-inset`).
+     * Default: `'0.75rem'` (12 px track zone → 4 px visible thumb after 4 px inset each side).
+     */
+    readonly scrollbarSize: import("@angular/core").InputSignal<string>;
+    /**
+     * When `true`, hides the custom scrollbar tracks and restores the browser's
+     * native scrollbar. Supports attribute syntax: `<mlv-scrollbar disabled>`.
+     */
+    readonly disabled: import("@angular/core").InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Custom aria-label override for the scrollable viewport region.
+     * Falls back to the i18n-provided label.
+     * Override when the component wraps content with a more specific purpose,
+     * e.g. `ariaLabel="Chat messages"`.
+     */
+    readonly ariaLabel: import("@angular/core").InputSignal<string | undefined>;
+    /**
+     * Tab index applied to the native scroll viewport.
+     *
+     * The default `0` means **auto**: the viewport is a tab stop only while its
+     * content holds nothing tabbable. A text-only region stays reachable so
+     * keyboard users can scroll it (WCAG 2.1.1), but a region full of form
+     * controls does not add a redundant stop in front of them — which is what
+     * put a focus ring around an entire dialog body on open.
+     *
+     * Any non-zero value is applied verbatim; composite widgets that manage
+     * their own focus pass `-1`.
+     */
+    readonly viewportTabIndex: import("@angular/core").InputSignal<number>;
+    /** @protected The component's i18n strings signal. */
+    protected readonly _i18n: import("@angular/core").Signal<import("@malva-ui/i18n").MlvScrollbarI18n> | null;
+    /** @protected Resolved aria-label: explicit input takes precedence over i18n default. */
+    protected readonly _resolvedAriaLabel: import("@angular/core").Signal<string>;
+    /**
+     * @protected Whether the scrolled content currently holds a tabbable element.
+     * Recomputed after render and on every content mutation.
+     */
+    protected readonly _hasTabbableContent: import("@angular/core").WritableSignal<boolean>;
+    /**
+     * @protected Tab index actually written to the viewport.
+     *
+     * `0` is treated as "auto" and collapses to `-1` once the content itself is
+     * keyboard-reachable; every other value passes through unchanged.
+     */
+    protected readonly _effectiveViewportTabIndex: import("@angular/core").Signal<number>;
+    /** @protected Whether the vertical track should be rendered. */
+    protected readonly _showVertical: import("@angular/core").Signal<boolean>;
+    /** @protected Whether the horizontal track should be rendered. */
+    protected readonly _showHorizontal: import("@angular/core").Signal<boolean>;
+    /** @protected True when scrollHeight > clientHeight (vertical overflow present). */
+    protected readonly _hasVerticalOverflow: import("@angular/core").WritableSignal<boolean>;
+    /** @protected True when scrollWidth > clientWidth (horizontal overflow present). */
+    protected readonly _hasHorizontalOverflow: import("@angular/core").WritableSignal<boolean>;
+    /** @protected Vertical thumb top offset in pixels (set as inline style). */
+    protected readonly _thumbTop: import("@angular/core").WritableSignal<number>;
+    /** @protected Vertical thumb height in pixels (set as inline style). */
+    protected readonly _thumbHeight: import("@angular/core").WritableSignal<number>;
+    /** @protected Horizontal thumb left offset in pixels (set as inline style). */
+    protected readonly _thumbLeft: import("@angular/core").WritableSignal<number>;
+    /** @protected Horizontal thumb width in pixels (set as inline style). */
+    protected readonly _thumbWidth: import("@angular/core").WritableSignal<number>;
+    /** @protected True while the user is actively dragging a thumb. Adds `--dragging` modifier. */
+    protected readonly _isDragging: import("@angular/core").WritableSignal<boolean>;
+    /** @protected True while scroll events are firing. Cleared after 150 ms idle. Adds `--scrolling` modifier. */
+    protected readonly _isScrolling: import("@angular/core").WritableSignal<boolean>;
+    /** @private Reference to the inner scrollable viewport element. */
+    private readonly _viewport;
+    /**
+     * The native scrollable viewport element.
+     * Lets wrapping components (e.g. `main[mlvPage]`) observe scroll position
+     * without reaching into the component's private DOM.
+     */
+    get viewportElement(): HTMLElement;
+    /** @private Reference to the vertical track element. */
+    private readonly _trackV;
+    /** @private Reference to the horizontal track element. */
+    private readonly _trackH;
+    /** @private Minimum rendered thumb length in pixels — prevents thumb from becoming unclickable. */
+    private readonly _minThumbSize;
+    /** @private Native ResizeObserver watching viewport and content size. */
+    private _resizeObserver;
+    /** @private Native MutationObserver keeping `_hasTabbableContent` in sync with projected content. */
+    private _contentObserver;
+    /** @private CDK checker used to decide whether projected content is keyboard-reachable. */
+    private readonly _interactivityChecker;
+    /** @private Timeout ID for clearing the `--scrolling` modifier after idle. */
+    private _scrollTimeout;
+    /** @private DestroyRef used to clean up the ResizeObserver, timers, and drag listeners. */
+    private readonly _destroyRef;
+    /** @private Renderer2 used so DOM listeners are SSR-safe and unsubscribable. */
+    private readonly _renderer;
+    constructor();
+    /**
+     * @private Re-reads whether the projected content contains a tab stop.
+     *
+     * Drives `_effectiveViewportTabIndex`: a scroll region only needs to be a tab
+     * stop of its own when nothing inside it already is (WCAG 2.1.1). Keeping it
+     * unconditionally tabbable put a redundant stop — and a focus ring around the
+     * whole region — in front of every dialog body's form controls.
+     */
+    private _updateTabbableContent;
+    /** @protected Handles scroll events on the viewport. Updates thumb positions and `--scrolling` state. */
+    protected _onScroll(): void;
+    /**
+     * @protected Handles `pointerdown` on a scrollbar thumb.
+     * Captures the pointer and translates subsequent `pointermove` deltas into
+     * viewport scroll offsets. Releases on `pointerup` or `pointercancel`.
+     */
+    protected _onThumbPointerDown(event: PointerEvent, axis: 'vertical' | 'horizontal'): void;
+    /**
+     * @private Recalculates overflow detection and thumb geometry.
+     * Called after first render, on ResizeObserver notifications, and on scroll.
+     */
+    private _updateGeometry;
+    /**
+     * @private Recomputes thumb position and size signals from the current viewport
+     * scroll state. Fast path — called on every scroll event.
+     */
+    private _updateThumbPositions;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvScrollbar, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MlvScrollbar, "mlv-scrollbar", never, { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "scrollbarSize": { "alias": "scrollbarSize"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "viewportTabIndex": { "alias": "viewportTabIndex"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}

package/scrollbar/malva-ui-core-scrollbar.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="@malva-ui/core/scrollbar" />
+export * from './index';

package/search-field/README.md

@@ -0,0 +1,32 @@
+# @malva-ui/core/search-field
+
+`mlv-search-field` is a search-specific input that supports two commit
+strategies while keeping one two-way bindable query model:
+
+- `trigger="live"` emits deduplicated searches after a configurable trailing
+  debounce (200 ms by default).
+- `trigger="submit"` emits only when the user presses Enter or activates the
+  submit button.
+- Clearing always cancels pending work and updates `value` to an empty query;
+  it also commits that query by default. Set `commitOnClear="false"` when a
+  composite consumer owns commit orchestration.
+- Disabled, loading, density, reduced-motion, keyboard, and translated-label
+  states use the shared Malva UI primitives and conventions.
+
+```html
+<mlv-search-field trigger="live" [debounce]="250" [(value)]="query" (search)="loadResults($event)" />
+```
+
+Set `role="combobox"` to drive a consumer-owned suggestion listbox. The field
+then stamps `role="combobox"` on its `<input>`, forwards `ariaControls` /
+`ariaExpanded` / `ariaAutocomplete` / `ariaActiveDescendant` onto the same
+element, and reports the option-navigation keys through `(navigate)`.
+`(commit)` fires on Enter and the submit action; calling `preventDefault()` on
+the event it carries takes the commit over, so Enter resolves the highlighted
+option instead of emitting `search`.
+
+```html
+<mlv-search-field role="combobox" ariaAutocomplete="list" [value]="query()" [ariaControls]="listboxId" [ariaExpanded]="open()" [ariaActiveDescendant]="activeOptionId()" (valueChange)="onQueryChange($event)" (navigate)="onNavigate($event)" (commit)="onCommit($event)" (search)="loadResults($event)" />
+```
+
+Run `yarn nx test core-search-field` to execute the focused unit tests.

package/search-field/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/search-field/search-field';
+export * from './lib/search-field/search-overlay-content';