@quadrel-enterprise-ui/framework 20.12.0 → 20.13.0

package/index.d.ts

@@ -861,6 +861,11 @@ interface QdFilterConfigData {
      * this property has to be set to false except for one filter
      * because only one filter per page can be connected with the router.
      *
+     * When mounting multiple filters in the same view, set `connectWithRouter: false` on every
+     * filter except the one that should own the URL.
+     *
+     * Note: This is the only router connector that defaults to `true` for historical reasons; all other router connectors default to `false`.
+     *
      * * @default true
      */
     connectWithRouter?: boolean;
@@ -1191,12 +1196,40 @@ declare class QdPushEventsService {
     static ɵprov: i0.ɵɵInjectableDeclaration<QdPushEventsService>;
 }
 
+/**
+ * Display label for an adapter's owning feature, used by the hub to format ownership-conflict
+ * error messages in user-facing terms (no internal service names leak into logs).
+ */
+interface QdRouterQueryParamFeatureLabel {
+    /**
+     * Title-cased noun phrase identifying the feature in user-facing framework messages,
+     * e.g. `"Page Tabs"`.
+     */
+    readonly name: string;
+    /**
+     * Lowercase plural noun phrase for inline prose in user-facing framework messages,
+     * e.g. `"page tabs"`.
+     */
+    readonly plural: string;
+}
+/**
+ * Options for `QdRouterQueryParamHubService.write()`.
+ */
+interface QdRouterQueryParamWriteOptions {
+    /**
+     * `true` replaces the current history entry; `false` pushes a new entry. When several
+     * `write()` calls in the same microtask disagree, `true` wins (so an initial replace is
+     * preserved when a follow-up write would otherwise push). The escalation is per-batch —
+     * after each flush the pending flag resets to `false`, so writes that arrive in the next
+     * microtask start a fresh batch with their own `replaceUrl` value.
+     */
+    readonly replaceUrl: boolean;
+}
 /**
  * Framework-wide funnel for syncing application state with the URL `?key=value` query string.
  *
- * Several Quadrel features mirror their state to the URL — the table's sort and pagination today,
- * filter, search, and `qd-page-tabs` over time. Without coordination they each call
- * `router.navigate(...)` directly, which produces two failure modes:
+ * Several Quadrel features mirror their state to the URL via per-feature adapters. Without
+ * coordination they each call `router.navigate(...)` directly, which produces two failure modes:
  *
  * 1. **Race**: two navigates issued in the same JS turn cancel each other. Only the last writer
  *    wins; the URL silently loses the cancelled feature's params.
@@ -1226,7 +1259,7 @@ declare class QdPushEventsService {
  *
  *   connect(state$: Observable<FilterState>, dispatch: (state: FilterState) => void): void {
  *     if (!this._hub.isAvailable()) return;
- *     if (!this._hub.claim(['filter'], this, this._destroyRef)) return;
+ *     if (!this._hub.claim(['filter'], this, this._destroyRef, { name: 'Filter', plural: 'filters' })) return;
  *
  *     this._hub
  *       .queryParams()
@@ -1235,7 +1268,7 @@ declare class QdPushEventsService {
  *
  *     state$
  *       .pipe(takeUntilDestroyed(this._destroyRef))
- *       .subscribe(state => this._hub.write({ filter: serializeFilter(state) }, false));
+ *       .subscribe(state => this._hub.write({ filter: serializeFilter(state) }, { replaceUrl: false }));
  *   }
  * }
  * ```
@@ -1263,6 +1296,7 @@ declare class QdRouterQueryParamHubService {
     private readonly _activatedRoute;
     private readonly _destroyRef;
     private readonly _ownership;
+    private readonly _ownerLabels;
     private readonly _destroyClaims;
     private readonly _navigationSettledSubject;
     private _pendingParams;
@@ -1309,11 +1343,16 @@ declare class QdRouterQueryParamHubService {
      * @param owner Stable identity of the caller — usually `this`. Used as the registry key.
      * @param destroyRef Optional. If provided, the hub releases the keys automatically when the
      *   `DestroyRef` fires. Pass the adapter's `inject(DestroyRef)` to make leaks impossible.
+     * @param featureLabel Optional. User-facing display label for the adapter's owning feature. The
+     *   hub uses it to format ownership-conflict error messages so application developers see the
+     *   feature names they configured (e.g. `Filter`, `Page Tabs`, `Table`) instead of internal
+     *   adapter class names. When omitted, the hub falls back to a generic `another adapter` phrase.
      * @returns `true` if every requested key is now owned by `owner`. `false` if at least one key
      *   was already owned by a different adapter; the registry is left untouched and `destroyRef`
      *   is not registered.
      */
-    claim(keys: readonly string[], owner: object, destroyRef?: DestroyRef): boolean;
+    claim(keys: readonly string[], owner: object, destroyRef?: DestroyRef, featureLabel?: QdRouterQueryParamFeatureLabel): boolean;
+    private formatOwnershipConflictMessage;
     /**
      * Drops `owner`'s claim on the given keys. Keys not owned by `owner` are left untouched —
      * a foreign release call cannot steal another adapter's ownership.
@@ -1363,13 +1402,10 @@ declare class QdRouterQueryParamHubService {
      *
      * @param params Partial map of query-param keys to their new values. Missing keys are not touched.
      *   An empty object short-circuits and is a no-op.
-     * @param replaceUrl `true` replaces the current history entry; `false` pushes a new entry.
-     *   When several `write()` calls in the same microtask disagree, `true` wins (so an initial
-     *   replace is preserved when a follow-up write would otherwise push). The escalation is
-     *   per-batch — after each flush the pending flag resets to `false`, so writes that arrive
-     *   in the next microtask start a fresh batch with their own `replaceUrl` argument.
+     * @param options Write options — see `QdRouterQueryParamWriteOptions` for the `replaceUrl`
+     *   semantics and per-batch escalation rules.
      */
-    write(params: Record<string, string | undefined>, replaceUrl: boolean): void;
+    write(params: Record<string, string | undefined>, options: QdRouterQueryParamWriteOptions): void;
     private replayCurrentRouterStateForLateSubscribers;
     private forwardSettlingRouterEventsToNavigationSettled;
     private registerAutoRelease;
@@ -11137,21 +11173,27 @@ declare class QdFilterService {
     static ɵprov: i0.ɵɵInjectableDeclaration<QdFilterService>;
 }
 
+/**
+ * Per-view adapter that syncs `QdFilterComponent` selection with the URL `?filter=` query
+ * param via `QdRouterQueryParamHubService`. Reads/parses on activation, writes on selection
+ * change. Coordination, ownership, and write batching are delegated to the hub — see its
+ * JSDoc for details. Behavior contracts live in `filter-router-connector.service.spec.ts`
+ * and `router-query-param-hub.integration.cy.ts`.
+ */
 declare class QdFilterRouterConnectorService {
-    private readonly filterService;
-    private readonly router;
-    private readonly activatedRoute;
+    private readonly _filterService;
+    private readonly _hub;
+    private readonly _destroyRef;
     private _connectedFilter?;
-    private _activatedRouteSubscription;
-    private _filterUrlParameterSubscription;
-    private _navigationEnded$;
+    private _readSubscription?;
+    private _writeSubscription?;
     private _activatedRouteCheckedSubject;
     private _activatedRouteChecked$;
     constructor();
     connectFilterWithRouter(filterComponent: QdFilterComponent): Observable<boolean>;
-    private setFilterSelectionFromUrl;
-    private setUrlOnFilterSelection;
-    disconnectFilterFromRouter(filterComponent: QdFilterComponent): void;
+    private tearDownConnection;
+    private subscribeToUrlChanges;
+    private subscribeToFilterChanges;
     static ɵfac: i0.ɵɵFactoryDeclaration<QdFilterRouterConnectorService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<QdFilterRouterConnectorService>;
 }
@@ -12669,13 +12711,16 @@ interface QdTabSelectionEvent {
  *
  * #### **Submit Button Configuration**
  *
- * The submit button at the bottom of the tab system can be configured via `QdPageTabsConfig`:
+ * The submit button at the bottom of the tab system can be configured via `QdPageTabsConfig.submitButton`:
  *
  * - **i18n**: The translated label for the submit button.
  * - **handler**: A callback function that receives form data upon submission.
  * - **isDisabled**: Controls whether the button should be active or not.
  * - **isHidden**: Determines whether the button is visible.
- * - **connectWithRouter**: If set to true, the tab will be connected to the URL and will be bookmarked. It is obligatory to set the `name` attribute for each tab.
+ *
+ * #### **Router Integration**
+ *
+ * - **connectWithRouter**: If set to true, the active tab is synced with the URL via the `?tab=<name>` query param and becomes bookmarkable. Each `<qd-page-tab>` then needs a unique `name`.
  *
  * #### **Usage**
  *
@@ -12791,11 +12836,10 @@ interface QdTabSelectionEvent {
  * - If an invalid tab name is provided in URL, the first available tab is selected
  * - If no tab parameter is present, the `selectedIndex` or first non-disabled tab is selected
  */
-declare class QdPageTabsComponent extends CdkStepper implements OnInit, OnChanges, AfterContentInit, AfterViewInit, OnDestroy {
+declare class QdPageTabsComponent extends CdkStepper implements OnInit, OnChanges, AfterContentInit, AfterViewInit {
     readonly footerService: QdPageFooterService;
     private pageStoreService;
-    private readonly router;
-    private readonly route;
+    private readonly routerConnector;
     /**
      * Configuration of QdPageTabs.
      */
@@ -12818,22 +12862,9 @@ declare class QdPageTabsComponent extends CdkStepper implements OnInit, OnChange
     ngAfterViewInit(): void;
     private initializeTabSelection;
     private configureBookmarkableTabs;
-    /**
-     * Initializes the tab selection based on the URL parameter 'tab'.
-     * @private
-     */
-    private initializeTabFromUrl;
-    /**
-     * If the user navigates to a page with a tab selected, the tab will be selected automatically in {@link initializeTabFromUrl()} method.
-     * If the user navigates to a page without a tab selected, the first active tab will be selected.
-     * @private
-     */
-    private initializeFirstTabSelection;
-    ngOnDestroy(): void;
     private isTabSelectable;
     /**
      * Selects the first tab that is not disabled.
-     * @param updateUrl if true, the URL will be updated to reflect the selected tab.
      */
     private selectFirstNotDisabledTab;
     save(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadrel-enterprise-ui/framework",
-  "version": "20.12.0",
+  "version": "20.13.0",
   "exports": {
     "./jest-preset": "./jest-preset.js",
     "./package.json": {