@dereekb/dbx-web 13.17.0 → 13.18.0

package/types/dereekb-dbx-web-style-demo.d.ts

@@ -0,0 +1,883 @@
+import { Maybe, CssStyleObject, ArrayOrValue, CssClass } from '@dereekb/util';
+import * as i0 from '@angular/core';
+import { Type, InjectionToken, EnvironmentProviders, Signal, ElementRef } from '@angular/core';
+import { DbxThemeColor, DbxColorTone } from '@dereekb/dbx-web';
+import { ClickableAnchorLinkTree } from '@dereekb/dbx-core';
+
+/**
+ * Identifier for a {@link DbxStyleDemoStyleTemplate} registered with the {@link DbxStyleDemoStyleLoaderService}.
+ *
+ * Use a kebab-case string (e.g. `'corner-shape-large'`) to reference a template by key.
+ */
+type DbxStyleDemoStyleTemplateKey = string;
+/**
+ * A named bundle of CSS-token overrides (and/or debug classes) the style-demo playground can toggle on a rendered region.
+ *
+ * Templates are the "levers" flipped in the showcase: applying one re-points CSS custom properties (e.g. `--mat-sys-*`)
+ * and/or attaches debug classes so that every dbx component beneath the loader host repaints live via the cascade.
+ *
+ * This type is demo/debug-only and disposable — it is not a dbx-web core runtime primitive.
+ */
+interface DbxStyleDemoStyleTemplate {
+    /**
+     * Unique key identifying this template.
+     */
+    readonly key: DbxStyleDemoStyleTemplateKey;
+    /**
+     * Inline CSS-token overrides applied to the loader host's `[style]` (e.g. `{ '--mat-sys-primary': '#ff0066' }`).
+     *
+     * When several templates are merged, later templates' style keys win.
+     */
+    readonly style?: Maybe<CssStyleObject>;
+    /**
+     * Debug class(es) applied to the loader host (e.g. `'dbx-style-demo-template-corner-shape-large'`).
+     *
+     * When several templates are merged, classes accumulate and de-duplicate (order-preserving).
+     */
+    readonly className?: Maybe<ArrayOrValue<CssClass>>;
+    /**
+     * Optional human-readable label shown in the controls UI. Falls back to the {@link key} when unset.
+     */
+    readonly label?: Maybe<string>;
+    /**
+     * When true, the template participates in the "curated" set surfaced as a default lever in the controls UI.
+     */
+    readonly curated?: Maybe<boolean>;
+}
+/**
+ * Configuration object accepted by the `[dbxStyleDemoStyleLoader]` directive when an inline list of templates
+ * (rather than a list of registered keys) should be applied.
+ *
+ * @example
+ * ```html
+ * <div [dbxStyleDemoStyleLoader]="{ templates: [{ key: 'pink', style: { '--mat-sys-primary': '#ff0066' } }] }">…</div>
+ * ```
+ */
+interface DbxStyleDemoStyleLoaderConfig {
+    /**
+     * Template keys to resolve through the service, and/or inline template objects to merge directly.
+     */
+    readonly templates: ArrayOrValue<DbxStyleDemoStyleTemplateKey | DbxStyleDemoStyleTemplate>;
+}
+/**
+ * Union accepted by the `[dbxStyleDemoStyleLoader]` directive input: one or more template keys, or a config object.
+ */
+type DbxStyleDemoStyleLoaderInput = ArrayOrValue<DbxStyleDemoStyleTemplateKey> | DbxStyleDemoStyleLoaderConfig;
+/**
+ * The flattened result of merging one or more {@link DbxStyleDemoStyleTemplate} entries.
+ *
+ * Ready to bind to a host element's `[style]` (the {@link style} POJO) and `[class]` (the {@link classes}).
+ */
+interface DbxStyleDemoStyleSet {
+    /**
+     * Merged inline CSS-token overrides (later templates win on conflicting keys).
+     */
+    readonly style: CssStyleObject;
+    /**
+     * Merged debug classes (de-duplicated, order-preserving).
+     */
+    readonly classes: CssClass[];
+}
+/**
+ * Merges an ordered list of {@link DbxStyleDemoStyleTemplate} entries into a single {@link DbxStyleDemoStyleSet}.
+ *
+ * Style POJOs are merged with `{ ...acc, ...template.style }` so later templates override earlier ones on
+ * conflicting token keys; classes accumulate across all templates and are de-duplicated order-preserving via
+ * {@link cssClassesSet}.
+ *
+ * @param templates - The templates to merge, in precedence order (earliest first, latest wins).
+ * @returns The merged style set.
+ *
+ * @example
+ * ```ts
+ * mergeDbxStyleDemoStyleTemplates([
+ *   { key: 'a', style: { '--mat-sys-primary': 'red' }, className: 'x' },
+ *   { key: 'b', style: { '--mat-sys-primary': 'blue' }, className: ['x', 'y'] }
+ * ]);
+ * // -> { style: { '--mat-sys-primary': 'blue' }, classes: ['x', 'y'] }
+ * ```
+ */
+declare function mergeDbxStyleDemoStyleTemplates(templates: DbxStyleDemoStyleTemplate[]): DbxStyleDemoStyleSet;
+/**
+ * Type guard: true when the value is a {@link DbxStyleDemoStyleTemplate} object (not a bare template-key string).
+ *
+ * @param value - The value to test.
+ * @returns `true` when the value is an object carrying a string `key`.
+ *
+ * @example
+ * ```ts
+ * isDbxStyleDemoStyleTemplate('corner-shape-large'); // false
+ * isDbxStyleDemoStyleTemplate({ key: 'corner-shape-large' }); // true
+ * ```
+ */
+declare function isDbxStyleDemoStyleTemplate(value: Maybe<DbxStyleDemoStyleTemplateKey | DbxStyleDemoStyleTemplate>): value is DbxStyleDemoStyleTemplate;
+/**
+ * Type guard: true when the directive input is a {@link DbxStyleDemoStyleLoaderConfig} (rather than a key / array of keys).
+ *
+ * @param value - The value to test.
+ * @returns `true` when the value is a non-array object carrying a `templates` property.
+ *
+ * @example
+ * ```ts
+ * isDbxStyleDemoStyleLoaderConfig('corner-shape-large'); // false
+ * isDbxStyleDemoStyleLoaderConfig(['a', 'b']); // false
+ * isDbxStyleDemoStyleLoaderConfig({ templates: ['a'] }); // true
+ * ```
+ */
+declare function isDbxStyleDemoStyleLoaderConfig(value: Maybe<DbxStyleDemoStyleLoaderInput>): value is DbxStyleDemoStyleLoaderConfig;
+
+/**
+ * Configuration provided in the root environment for seeding {@link DbxStyleDemoStyleLoaderService} with initial templates.
+ *
+ * Registered via `provideDbxStyleDemo({ templates: [...] })`.
+ */
+declare abstract class DbxStyleDemoStyleLoaderServiceConfig {
+    /**
+     * Templates to register at service construction time.
+     */
+    abstract readonly templates?: Maybe<DbxStyleDemoStyleTemplate[]>;
+}
+/**
+ * Registry of named {@link DbxStyleDemoStyleTemplate} levers used by the style-demo playground.
+ *
+ * Mirrors the shape of `DbxColorService`: app-provided templates are seeded from an optional
+ * {@link DbxStyleDemoStyleLoaderServiceConfig}, then resolved by key at render time by the
+ * `[dbxStyleDemoStyleLoader]` directive. Ships with no built-in templates — every lever is contributed by an app.
+ *
+ * This service is demo/debug-only and disposable — it is not a dbx-web core runtime primitive.
+ *
+ * @example
+ * ```ts
+ * const loader = inject(DbxStyleDemoStyleLoaderService);
+ * loader.register({ key: 'pink', style: { '--mat-sys-primary': '#ff0066' } });
+ * loader.mergeTemplates(['pink']);
+ * // -> { style: { '--mat-sys-primary': '#ff0066' }, classes: [] }
+ * ```
+ */
+declare class DbxStyleDemoStyleLoaderService {
+    private readonly _templates;
+    constructor();
+    /**
+     * Registers one or more {@link DbxStyleDemoStyleTemplate} entries.
+     *
+     * @param templates - The template(s) to register.
+     * @param override - Whether existing entries with the same key should be replaced (default true)
+     */
+    register(templates: ArrayOrValue<DbxStyleDemoStyleTemplate>, override?: boolean): void;
+    /**
+     * Returns whether a template with the given key has been registered.
+     *
+     * @param key - The template key to check.
+     * @returns True when a template is registered under the given key.
+     */
+    hasTemplate(key: DbxStyleDemoStyleTemplateKey): boolean;
+    /**
+     * Returns the {@link DbxStyleDemoStyleTemplate} registered under the given key, or undefined if none.
+     *
+     * @param key - The template key to look up.
+     * @returns The registered template, or undefined when no template matches.
+     */
+    getTemplate(key: DbxStyleDemoStyleTemplateKey): Maybe<DbxStyleDemoStyleTemplate>;
+    /**
+     * Returns all currently registered template keys, in registration order.
+     *
+     * @returns Array of all registered template keys.
+     */
+    getAllRegisteredTemplateKeys(): DbxStyleDemoStyleTemplateKey[];
+    /**
+     * Returns all registered templates flagged {@link DbxStyleDemoStyleTemplate.curated}, in registration order.
+     *
+     * @returns The curated templates in insertion order.
+     */
+    getCuratedTemplates(): DbxStyleDemoStyleTemplate[];
+    /**
+     * Resolves a mix of template keys and inline templates into a single merged {@link DbxStyleDemoStyleSet}.
+     *
+     * String keys are resolved through the registry; unknown keys are skipped. Inline template objects are
+     * used as-is. Resolution preserves input order so later entries win on conflicting style keys.
+     *
+     * @param keysOrTemplates - Template keys and/or inline templates to merge, in precedence order.
+     * @returns The merged style set.
+     *
+     * @example
+     * ```ts
+     * loader.register({ key: 'pink', style: { '--mat-sys-primary': '#ff0066' } });
+     * loader.mergeTemplates(['pink', 'unknown', { key: 'inline', className: 'demo' }]);
+     * // -> { style: { '--mat-sys-primary': '#ff0066' }, classes: ['demo'] }
+     * ```
+     */
+    mergeTemplates(keysOrTemplates: ArrayOrValue<DbxStyleDemoStyleTemplateKey | DbxStyleDemoStyleTemplate>): DbxStyleDemoStyleSet;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoStyleLoaderService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DbxStyleDemoStyleLoaderService>;
+}
+
+/**
+ * Applies a merged bundle of style-demo template levers to its host element, repainting every dbx component
+ * beneath it via the CSS custom-property cascade.
+ *
+ * The input accepts either one or more registered template keys (`ArrayOrValue<DbxStyleDemoStyleTemplateKey>`) or a
+ * {@link DbxStyleDemoStyleLoaderConfig} carrying inline template objects. The {@link DbxStyleDemoStyleLoaderService} is
+ * optional-injected: when present, string keys are resolved through the registry (unknown keys skipped); when absent,
+ * only inline template objects are merged (string keys are unresolvable and skipped). Merged inline CSS-token overrides
+ * bind to the host `[style]` and merged debug classes bind to the host `[class]`.
+ *
+ * This directive is demo/debug-only and disposable — it is not a dbx-web core runtime primitive.
+ *
+ * @example
+ * ```html
+ * <div [dbxStyleDemoStyleLoader]="['corner-shape-large', 'surface-tint']">…</div>
+ * <div [dbxStyleDemoStyleLoader]="{ templates: [{ key: 'pink', style: { '--mat-sys-primary': '#ff0066' } }] }">…</div>
+ * ```
+ */
+declare class DbxStyleDemoStyleLoaderDirective {
+    private readonly _loaderService;
+    /**
+     * Template keys to resolve through the service, or a config object carrying inline templates.
+     */
+    readonly dbxStyleDemoStyleLoader: i0.InputSignal<Maybe<DbxStyleDemoStyleLoaderInput>>;
+    private readonly _mergedSignal;
+    readonly styleSignal: i0.Signal<Maybe<CssStyleObject>>;
+    readonly classesSignal: i0.Signal<string>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoStyleLoaderDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<DbxStyleDemoStyleLoaderDirective, "[dbxStyleDemoStyleLoader]", never, { "dbxStyleDemoStyleLoader": { "alias": "dbxStyleDemoStyleLoader"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Identifier for a {@link DbxStyleDemoSection}, unique across all registered sections.
+ */
+type DbxStyleDemoSectionId = string;
+/**
+ * A single showcase region rendered by the style-demo playground.
+ *
+ * Each section is a standalone component demonstrating a styling pattern; the playground renders enabled
+ * sections beneath the style-loader host so they repaint live as template levers are toggled.
+ */
+interface DbxStyleDemoSection {
+    /**
+     * Identifier, unique across all registered sections.
+     */
+    readonly id: DbxStyleDemoSectionId;
+    /**
+     * Human-readable title shown in the section's card header and the controls toggle list.
+     */
+    readonly title: string;
+    /**
+     * Optional grouping label used to cluster sections in the controls UI (e.g. `'cards'`, `'color'`).
+     */
+    readonly group?: Maybe<string>;
+    /**
+     * Optional tags used to filter which sections a playground instance renders.
+     */
+    readonly tags?: Maybe<string[]>;
+    /**
+     * The standalone component rendered for this section.
+     */
+    readonly component: Type<unknown>;
+    /**
+     * Whether the section is enabled by default when the playground first renders. Defaults to true.
+     */
+    readonly defaultEnabled?: Maybe<boolean>;
+}
+/**
+ * A library's contribution of sections to the style-demo playground, registered via `provideDbxStyleDemoSections`.
+ */
+interface DbxStyleDemoSectionGroup {
+    /**
+     * Identifier of the contributing library (e.g. `'dbx-web'`, `'dbx-form'`).
+     */
+    readonly libId: string;
+    /**
+     * The sections this library contributes.
+     */
+    readonly sections: DbxStyleDemoSection[];
+}
+
+/**
+ * Multi-provider injection token collecting every {@link DbxStyleDemoSectionGroup} contributed by an app's libraries.
+ *
+ * Injected by {@link DbxStyleDemoSectionRegistry} (as an array) to assemble the full set of showcase sections.
+ */
+declare const DBX_STYLE_DEMO_SECTION_GROUP: InjectionToken<DbxStyleDemoSectionGroup>;
+/**
+ * Registers a library's {@link DbxStyleDemoSectionGroup} with the style-demo playground.
+ *
+ * Each call contributes one group via the {@link DBX_STYLE_DEMO_SECTION_GROUP} multi-provider, so several libraries
+ * (e.g. `provideDbxWebStyleDemo()`, `provideDbxFormStyleDemo()`) can each add their own sections.
+ *
+ * @param group - The section group to register.
+ * @returns EnvironmentProviders contributing the group.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+declare function provideDbxStyleDemoSections(group: DbxStyleDemoSectionGroup): EnvironmentProviders;
+
+/**
+ * Root service that flattens every {@link DbxStyleDemoSectionGroup} registered via {@link provideDbxStyleDemoSections}
+ * into a single ordered list of {@link DbxStyleDemoSection} entries.
+ *
+ * Consumed by the `<dbx-style-demo>` playground to determine which sections are available to render.
+ */
+declare class DbxStyleDemoSectionRegistry {
+    /**
+     * All registered sections, in library-registration then section-declaration order.
+     */
+    readonly sectionsSignal: Signal<DbxStyleDemoSection[]>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoSectionRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DbxStyleDemoSectionRegistry>;
+}
+
+/**
+ * A user-facing lever in the style-demo controls that toggles a registered {@link DbxStyleDemoStyleTemplate} on/off.
+ *
+ * Active toggles are collected by the playground and fed to the `[dbxStyleDemoStyleLoader]` host so their token
+ * overrides ripple through every rendered section.
+ */
+interface DbxStyleDemoTemplateToggle {
+    /**
+     * Key of the registered {@link DbxStyleDemoStyleTemplate} this toggle activates.
+     */
+    readonly templateName: DbxStyleDemoStyleTemplateKey;
+    /**
+     * Human-readable label shown in the controls UI.
+     */
+    readonly label: string;
+    /**
+     * Optional grouping label used to cluster toggles in the controls UI (e.g. `'Shape'`, `'Surface'`).
+     *
+     * Toggles sharing a non-null group are treated as mutually exclusive (radio-like): activating one in the controls
+     * deactivates the others in the same group. Ungrouped toggles (`null`/`undefined` group) toggle independently.
+     */
+    readonly group?: Maybe<string>;
+}
+/**
+ * A cluster of {@link DbxStyleDemoTemplateToggle}s sharing the same {@link DbxStyleDemoTemplateToggle.group} label.
+ *
+ * Produced by {@link groupDbxStyleDemoTemplateToggles} so the controls UI can render each group under a sub-label.
+ */
+interface DbxStyleDemoTemplateToggleGroup {
+    /**
+     * The shared group label, or `null` for the leading cluster of ungrouped toggles.
+     */
+    readonly label: Maybe<string>;
+    /**
+     * The toggles in this cluster, in their original registration order.
+     */
+    readonly toggles: DbxStyleDemoTemplateToggle[];
+}
+/**
+ * Clusters template toggles by their {@link DbxStyleDemoTemplateToggle.group} label for grouped rendering.
+ *
+ * The ungrouped cluster (`label: null`) is emitted first when any ungrouped toggle exists, followed by each named
+ * group in first-seen order. Toggle order within a cluster is preserved.
+ *
+ * @param toggles - The toggles to cluster.
+ * @returns The clusters in render order.
+ *
+ * @example
+ * ```ts
+ * groupDbxStyleDemoTemplateToggles([
+ *   { templateName: 'a', label: 'A' },
+ *   { templateName: 'b', label: 'B', group: 'Shape' },
+ *   { templateName: 'c', label: 'C', group: 'Shape' }
+ * ]);
+ * // -> [{ label: null, toggles: [A] }, { label: 'Shape', toggles: [B, C] }]
+ * ```
+ */
+declare function groupDbxStyleDemoTemplateToggles(toggles: DbxStyleDemoTemplateToggle[]): DbxStyleDemoTemplateToggleGroup[];
+
+/**
+ * Multi-provider injection token collecting every {@link DbxStyleDemoTemplateToggle} contributed by an app's libraries.
+ *
+ * Injected by the `<dbx-style-demo>` playground (as an array) to populate the template-lever list in the controls UI.
+ */
+declare const DBX_STYLE_DEMO_TEMPLATE_TOGGLE: InjectionToken<DbxStyleDemoTemplateToggle>;
+/**
+ * Registers one or more {@link DbxStyleDemoTemplateToggle} levers with the style-demo playground.
+ *
+ * Each toggle is contributed via the {@link DBX_STYLE_DEMO_TEMPLATE_TOGGLE} multi-provider, so several libraries can
+ * each add their own levers.
+ *
+ * @param toggles - The template toggles to register.
+ * @returns EnvironmentProviders contributing the toggles.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+declare function provideDbxStyleDemoTemplateToggles(...toggles: DbxStyleDemoTemplateToggle[]): EnvironmentProviders;
+
+/**
+ * Detach key used by the style-demo controls detach panel.
+ */
+declare const DBX_STYLE_DEMO_CONTROLS_DETACH_KEY = "dbx-style-demo-controls";
+/**
+ * Injection token carrying the component class rendered inside the style-demo controls detach panel.
+ *
+ * `DbxStyleDemoControlsService` opens this component via `DbxDetachService` (so it survives navigation and is available
+ * app-wide) reading the service's {@link DbxStyleDemoControls} state. When unregistered, the controls buttons are hidden.
+ *
+ * `@dereekb/dbx-form/style-demo` registers `DbxFormStyleDemoControlsDetachComponent` (a presets chip-field controls UI)
+ * here — the controls UI lives in dbx-form because it depends on `@dereekb/dbx-form`'s pickable chip field, which dbx-web
+ * cannot import.
+ */
+declare const DBX_STYLE_DEMO_CONTROLS_COMPONENT: InjectionToken<Type<unknown>>;
+/**
+ * Popover key used by the style-demo sections popover, opened from the playground header.
+ */
+declare const DBX_STYLE_DEMO_SECTIONS_POPOVER_KEY = "dbx-style-demo-sections";
+/**
+ * Injection token carrying the component class rendered inside the style-demo sections popover.
+ *
+ * `DbxStyleDemoControlsService` opens this component via `DbxPopoverService`, anchored to the playground header's
+ * "Sections" button, because sections only affect the `<dbx-style-demo>` playground page (unlike presets, which restyle
+ * the whole app). When unregistered, the playground's "Sections" button is hidden.
+ *
+ * `@dereekb/dbx-form/style-demo` registers `DbxFormStyleDemoSectionsPopoverComponent` (a sections chip-field controls
+ * UI) here — the controls UI lives in dbx-form because it depends on `@dereekb/dbx-form`'s pickable chip field, which
+ * dbx-web cannot import.
+ */
+declare const DBX_STYLE_DEMO_SECTIONS_COMPONENT: InjectionToken<Type<unknown>>;
+/**
+ * Configuration for the `<dbx-style-demo>` playground.
+ */
+interface DbxStyleDemoConfig {
+    /**
+     * When set, only sections whose tags intersect this list are rendered. When unset, all registered sections render.
+     */
+    readonly tags?: Maybe<string[]>;
+    /**
+     * Reserved for Phase 2 drag/drop section reordering. Accepted but ignored in v1.
+     */
+    readonly enableDragDrop?: Maybe<boolean>;
+    /**
+     * Template keys to activate by default when the playground first renders.
+     */
+    readonly defaultActiveTemplates?: Maybe<DbxStyleDemoStyleTemplateKey[]>;
+}
+/**
+ * The reactive control surface a `<dbx-style-demo>` playground exposes to its controls popover.
+ *
+ * The popover reads the signals to render its toggle lists and calls the setters to write the user's choices
+ * back to the playground, where they drive the rendered sections and the active style-loader templates.
+ */
+interface DbxStyleDemoControls {
+    /**
+     * The sections available to render (already filtered by the playground's configured tags).
+     */
+    readonly sectionsSignal: Signal<DbxStyleDemoSection[]>;
+    /**
+     * The ids of the currently-enabled (visible) sections.
+     */
+    readonly enabledIdsSignal: Signal<Set<DbxStyleDemoSectionId>>;
+    /**
+     * The registered template-lever toggles.
+     */
+    readonly templateTogglesSignal: Signal<DbxStyleDemoTemplateToggle[]>;
+    /**
+     * The keys of the currently-active template levers.
+     */
+    readonly activeTemplateKeysSignal: Signal<Set<DbxStyleDemoStyleTemplateKey>>;
+    /**
+     * Enables or disables a section by id.
+     */
+    setSectionEnabled(id: DbxStyleDemoSectionId, enabled: boolean): void;
+    /**
+     * Activates or deactivates a template lever by key.
+     *
+     * Activating a lever that belongs to a non-null toggle group deactivates the other active levers in that group
+     * (radio-like), so only one lever per group is active at a time.
+     */
+    setTemplateActive(key: DbxStyleDemoStyleTemplateKey, active: boolean): void;
+}
+
+/**
+ * Configuration for the {@link DbxStyleDemoControlsService}, provided in the root environment via `provideDbxStyleDemo()`.
+ */
+declare abstract class DbxStyleDemoControlsServiceConfig {
+    /**
+     * When false, the service does not forward its active style levers into the {@link DbxStyleService} as a body
+     * supplement, so levers only repaint the playground subtree. Defaults to true.
+     */
+    abstract readonly applyStylesToApp?: Maybe<boolean>;
+}
+/**
+ * Root-level state holder for the `<dbx-style-demo>` controls, implementing {@link DbxStyleDemoControls}.
+ *
+ * Owning the enabled-sections / active-template state here (rather than in the playground component) lets the controls
+ * panel open through {@link DbxDetachService} so it survives navigation and is available app-wide. When a
+ * {@link DbxStyleService} is available (and {@link DbxStyleDemoControlsServiceConfig.applyStylesToApp} is not false), the
+ * active levers are forwarded into the style service as a body supplement so they repaint the entire app.
+ *
+ * This service is demo/debug-only and disposable — it is not a dbx-web core runtime primitive.
+ */
+declare class DbxStyleDemoControlsService implements DbxStyleDemoControls {
+    private readonly _registry;
+    private readonly _toggles;
+    private readonly _loaderService;
+    private readonly _detachService;
+    private readonly _popoverService;
+    private readonly _controlsComponentClass;
+    private readonly _sectionsComponentClass;
+    private readonly _styleService;
+    private readonly _config;
+    private readonly _sectionEnabledOverrides;
+    private readonly _activeTemplateKeysOverride;
+    private readonly _defaultActiveTemplateKeys;
+    /**
+     * True when a controls component is registered, gating the controls buttons.
+     */
+    readonly hasControlsSignal: Signal<boolean>;
+    /**
+     * True when a sections component is registered (and a popover service is available), gating the playground's
+     * "Sections" button.
+     */
+    readonly hasSectionsSignal: Signal<boolean>;
+    /**
+     * All registered sections, unfiltered (the global controls list every section).
+     */
+    readonly sectionsSignal: Signal<DbxStyleDemoSection[]>;
+    readonly templateTogglesSignal: Signal<DbxStyleDemoTemplateToggle[]>;
+    readonly enabledIdsSignal: Signal<Set<string>>;
+    readonly activeTemplateKeysSignal: Signal<Set<string>>;
+    readonly activeTemplateKeysArraySignal: Signal<string[]>;
+    constructor();
+    setSectionEnabled(id: DbxStyleDemoSectionId, enabled: boolean): void;
+    setTemplateActive(key: DbxStyleDemoStyleTemplateKey, active: boolean): void;
+    /**
+     * Seeds the default active template keys. Has no effect once the user has set an override via {@link setTemplateActive}.
+     *
+     * @param keys - The template keys to activate by default.
+     */
+    setDefaultActiveTemplates(keys: DbxStyleDemoStyleTemplateKey[]): void;
+    /**
+     * Opens the registered controls component in a draggable detached overlay. No-op when no controls component is registered.
+     */
+    openControls(): void;
+    /**
+     * Opens the registered sections component in a popover anchored to the given origin. No-op when no sections component
+     * is registered (or no popover service is available). Symmetric with {@link openControls}.
+     *
+     * @param config - The popover configuration.
+     * @param config.origin - The element the popover anchors to (the playground header's "Sections" button).
+     */
+    openSectionsPopover(config: {
+        readonly origin: ElementRef;
+    }): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoControlsService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DbxStyleDemoControlsService>;
+}
+
+/**
+ * Drop-in styling showcase for dbx-components apps.
+ *
+ * Renders the registered {@link DbxStyleDemoSection} components beneath a `[dbxStyleDemoStyleLoader]` host so they
+ * paint purely through the host app's `--mat-sys-*` / `--dbx-*` tokens and `.dbx-*` utilities — the playground emits
+ * no theme of its own. The "Style controls" button opens the shared {@link DbxStyleDemoControlsService} detach panel
+ * (also reachable from the app toolbar); flipping a lever re-points CSS tokens that ripple through every rendered
+ * section live via the custom-property cascade. The button only appears when a controls component is registered.
+ *
+ * Section enablement and active levers are held globally in {@link DbxStyleDemoControlsService}; this playground only
+ * adds its own tag filtering on top of the global enabled state.
+ *
+ * This component is demo/debug-only and disposable — it is not a dbx-web core runtime primitive.
+ *
+ * @example
+ * ```html
+ * <dbx-style-demo [config]="{ defaultActiveTemplates: ['corner-shape-full'] }"></dbx-style-demo>
+ * ```
+ */
+declare class DbxStyleDemoComponent {
+    private readonly _registry;
+    private readonly _controlsService;
+    /**
+     * Playground configuration.
+     */
+    readonly config: i0.InputSignal<Maybe<DbxStyleDemoConfig>>;
+    /**
+     * True when a controls component is registered, gating the "Style controls" button.
+     */
+    readonly hasControlsSignal: Signal<boolean>;
+    /**
+     * True when a sections component is registered, gating the "Sections" button (which opens the sections popover).
+     */
+    readonly hasSectionsSignal: Signal<boolean>;
+    /**
+     * The "Sections" button element, used as the sections popover's anchor origin (present only while the button renders).
+     */
+    readonly sectionsButton: Signal<Maybe<ElementRef<any>>>;
+    /**
+     * The active template keys held by the controls service, applied to this playground's style-loader host.
+     */
+    readonly activeTemplatesSignal: Signal<string[]>;
+    /**
+     * The registry sections this playground instance considers, filtered by its configured tags (enablement stays global).
+     */
+    readonly sectionsSignal: Signal<DbxStyleDemoSection[]>;
+    readonly visibleSectionsSignal: Signal<DbxStyleDemoSection[]>;
+    /**
+     * Seeds the controls service with this playground's configured default active templates.
+     */
+    protected readonly _seedDefaultTemplatesEffect: i0.EffectRef;
+    openControls(): void;
+    openSectionsPopover(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DbxStyleDemoComponent, "dbx-style-demo", never, { "config": { "alias": "config"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * One Material button appearance shown in the {@link DbxStyleDemoButtonsSectionComponent} grid.
+ */
+type DbxStyleDemoButtonVariant = 'basic' | 'stroked' | 'flat' | 'raised' | 'tonal';
+/**
+ * Style-demo section showing every `dbx-button` appearance (basic, stroked, flat, raised, tonal) across the core
+ * theme colors, plus an icon-only and a FAB button. Buttons paint their container colour and corner radius from the
+ * `--mat-button-*` tokens, so they respond live to the playground's Shape levers and flip with light/dark.
+ *
+ * @dbxDocsUiExample
+ * @dbxDocsUiExampleSlug style-demo-buttons
+ * @dbxDocsUiExampleCategory style-demo
+ * @dbxDocsUiExampleSummary dbx-button appearances across theme colors, plus icon-only and FAB modes.
+ * @dbxDocsUiExampleRelated button, icon-button
+ */
+declare class DbxStyleDemoButtonsSectionComponent {
+    readonly variants: DbxStyleDemoButtonVariant[];
+    readonly colors: Maybe<DbxThemeColor>[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoButtonsSectionComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DbxStyleDemoButtonsSectionComponent, "dbx-style-demo-buttons-section", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Style-demo section showing the three Material 3 card appearances (outlined, raised, filled) painted purely
+ * from `--mat-sys-*` surface tokens, so they respond live to the playground's surface-tint and corner-shape levers.
+ *
+ * @dbxDocsUiExample
+ * @dbxDocsUiExampleSlug style-demo-cards
+ * @dbxDocsUiExampleCategory style-demo
+ * @dbxDocsUiExampleSummary Material 3 card appearances (outlined, elevated, filled) painted from system surface tokens.
+ * @dbxDocsUiExampleRelated mat-card, dbx-card-box
+ */
+declare class DbxStyleDemoCardsSectionComponent {
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoCardsSectionComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DbxStyleDemoCardsSectionComponent, "dbx-style-demo-cards-section", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * A registered color template surfaced as a swatch in the {@link DbxStyleDemoColorTemplatesSectionComponent}.
+ */
+interface DbxStyleDemoColorTemplate {
+    readonly key: string;
+    readonly curated: boolean;
+}
+/**
+ * Style-demo section that dumps every template registered with the host app's {@link DbxColorService} as a
+ * `[dbxColor]` swatch, marking the curated ones. This makes both the built-in curated set and any app-seeded
+ * templates visible in one place; when the service is not provided, an empty-state hint is shown instead.
+ *
+ * @dbxDocsUiExample
+ * @dbxDocsUiExampleSlug style-demo-color-templates
+ * @dbxDocsUiExampleCategory style-demo
+ * @dbxDocsUiExampleSummary Every registered DbxColorService template dumped as a [dbxColor] swatch, curated ones marked.
+ * @dbxDocsUiExampleRelated color, color-service
+ */
+declare class DbxStyleDemoColorTemplatesSectionComponent {
+    private readonly _colorService;
+    readonly templates: DbxStyleDemoColorTemplate[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoColorTemplatesSectionComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DbxStyleDemoColorTemplatesSectionComponent, "dbx-style-demo-color-templates-section", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Style-demo section showing `[dbxColor]` themed backgrounds at full strength and as `[dbxColorTone]` tonal washes,
+ * across the core and extra theme colors, so the color tokens are easy to compare under the host app's theme.
+ *
+ * @dbxDocsUiExample
+ * @dbxDocsUiExampleSlug style-demo-color-tones
+ * @dbxDocsUiExampleCategory style-demo
+ * @dbxDocsUiExampleSummary Themed [dbxColor] backgrounds at full strength and as [dbxColorTone] tonal washes.
+ * @dbxDocsUiExampleRelated color, text-color, color-service
+ */
+declare class DbxStyleDemoColorTonesSectionComponent {
+    readonly colors: DbxThemeColor[];
+    readonly tones: DbxColorTone[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoColorTonesSectionComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DbxStyleDemoColorTonesSectionComponent, "dbx-style-demo-color-tones-section", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Style-demo section showing the router-free navigation building blocks — `dbx-pagebar`, `dbx-bar` + `dbx-bar-header`,
+ * and a nested `dbx-anchor-list` — painted from the host theme's bar / surface tokens. The anchors are click-only, so
+ * this section needs no router; the route-bound `dbx-navbar` demo is contributed by the host app instead.
+ *
+ * @dbxDocsUiExample
+ * @dbxDocsUiExampleSlug style-demo-navigation
+ * @dbxDocsUiExampleCategory style-demo
+ * @dbxDocsUiExampleSummary Router-free navigation building blocks — pagebar, bar, bar-header, and a nested anchor list.
+ * @dbxDocsUiExampleRelated pagebar, bar, bar-header, anchor-list
+ */
+declare class DbxStyleDemoNavigationSectionComponent {
+    readonly navAnchors: ClickableAnchorLinkTree[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoNavigationSectionComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DbxStyleDemoNavigationSectionComponent, "dbx-style-demo-navigation-section", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * A single step of the Material 3 corner-radius scale shown in the {@link DbxStyleDemoShapeScaleSectionComponent}.
+ */
+interface DbxStyleDemoShapeStep {
+    readonly label: string;
+    /**
+     * The radius applied to the sample tile — a `var(--mat-sys-corner-*)` reference where a web token exists,
+     * otherwise the literal px value from the spec.
+     */
+    readonly radius: string;
+    /**
+     * The `--mat-sys-corner-*` token backing this step, or `null` when the M3 spec step has no web token.
+     */
+    readonly webToken?: Maybe<string>;
+}
+/**
+ * Style-demo section showing the full Material 3 corner-radius scale (per
+ * https://m3.material.io/styles/shape/corner-radius-scale) as fixed-size tiles, flagging the spec steps that have no
+ * web token. A live outlined card + stroked button below follow whichever Shape lever is active, demonstrating that
+ * the levers override the component shape tokens (`--mat-card-*` / `--mat-button-*`), not `--mat-sys-corner-*`.
+ *
+ * @dbxDocsUiExample
+ * @dbxDocsUiExampleSlug style-demo-shape-scale
+ * @dbxDocsUiExampleCategory style-demo
+ * @dbxDocsUiExampleSummary The Material 3 corner-radius scale as fixed tiles, flagging spec steps with no web token.
+ * @dbxDocsUiExampleRelated cards, button
+ */
+declare class DbxStyleDemoShapeScaleSectionComponent {
+    readonly steps: DbxStyleDemoShapeStep[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoShapeScaleSectionComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DbxStyleDemoShapeScaleSectionComponent, "dbx-style-demo-shape-scale-section", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * A single labeled swatch in the {@link DbxStyleDemoSurfacesSectionComponent} ramp.
+ */
+interface DbxStyleDemoSurface {
+    readonly label: string;
+    readonly background: string;
+    readonly color: string;
+}
+/**
+ * A single bordered outline sample in the {@link DbxStyleDemoSurfacesSectionComponent}.
+ */
+interface DbxStyleDemoOutline {
+    readonly label: string;
+    readonly border: string;
+}
+/**
+ * Style-demo section showing the full Material 3 surface ramp (`surface-dim` → `surface-container-highest`, plus
+ * `inverse-surface`) painted straight from the `--mat-sys-*` tokens, so the host theme's neutral palette and the
+ * playground's surface-tint lever are easy to read under light and dark.
+ *
+ * @dbxDocsUiExample
+ * @dbxDocsUiExampleSlug style-demo-surfaces
+ * @dbxDocsUiExampleCategory style-demo
+ * @dbxDocsUiExampleSummary The Material 3 surface ramp painted from --mat-sys-surface* tokens, plus outline samples.
+ * @dbxDocsUiExampleRelated cards, color
+ */
+declare class DbxStyleDemoSurfacesSectionComponent {
+    readonly surfaces: DbxStyleDemoSurface[];
+    readonly outlines: DbxStyleDemoOutline[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoSurfacesSectionComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DbxStyleDemoSurfacesSectionComponent, "dbx-style-demo-surfaces-section", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * A single M3 typescale role rendered in the {@link DbxStyleDemoTypeRolesSectionComponent} sample.
+ */
+interface DbxStyleDemoTypeRole {
+    readonly cssClass: string;
+    readonly label: string;
+}
+/**
+ * Style-demo section showing the Material 3 typescale roles via the `.dbx-text-<role>` utility classes, so the
+ * host theme's type ramp (family, size, weight, tracking) is visible at a glance.
+ *
+ * @dbxDocsUiExample
+ * @dbxDocsUiExampleSlug style-demo-type-roles
+ * @dbxDocsUiExampleCategory style-demo
+ * @dbxDocsUiExampleSummary Material 3 typescale roles rendered via the .dbx-text-<role> utility classes.
+ * @dbxDocsUiExampleRelated text
+ */
+declare class DbxStyleDemoTypeRolesSectionComponent {
+    readonly roles: DbxStyleDemoTypeRole[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbxStyleDemoTypeRolesSectionComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DbxStyleDemoTypeRolesSectionComponent, "dbx-style-demo-type-roles-section", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * The starter set of style-lever templates contributed by `@dereekb/dbx-web/style-demo`.
+ *
+ * The five `corner-shape-*` levers, the controls-only `pill-controls`, the component-scoped `button-corner-*` /
+ * `list-corner-*` / `anchor-list-corner-*` levers, and `surface-tint` reference the disposable
+ * `.dbx-style-demo-template-*` debug classes (emitted by the `dbx-style-demo-debug-classes()` SCSS mixin); the
+ * `vivid-primary` `style` lever applies an inline CSS-token override directly. The `corner-shape-*` levers share the
+ * `'Shape'` toggle group, so only one is active at a time; `pill-controls` (`'Controls'`), `button-corner-*`
+ * (`'Button Shape'`), `list-corner-*` (`'List Shape'`) and `anchor-list-corner-*` (`'Anchor List Shape'`) each live in
+ * their own group so they compose on top of a corner lever instead of radio-excluding it — their debug classes are
+ * emitted after `corner-shape-*` / `pill-controls` so they win the shape tokens they share.
+ */
+declare const DBX_WEB_STYLE_DEMO_TEMPLATES: DbxStyleDemoStyleTemplate[];
+/**
+ * The controls levers exposed for {@link DBX_WEB_STYLE_DEMO_TEMPLATES}.
+ *
+ * The `corner-shape-*` levers share the `'Shape'` group (mutually exclusive); the component-scoped `button-corner-*`
+ * (`'Button Shape'`), `list-corner-*` (`'List Shape'`) and `anchor-list-corner-*` (`'Anchor List Shape'`) levers are
+ * mutually exclusive within their own groups but compose with `'Shape'` and `'Controls'`, letting a global corner
+ * preset be overridden for just buttons, just `dbx-list` rows, or just `dbx-anchor-list` (nav) rows. `pill-controls`
+ * (`'Controls'`), `surface-tint` and `vivid-primary` are independent toggles in their own groups.
+ */
+declare const DBX_WEB_STYLE_DEMO_TEMPLATE_TOGGLES: DbxStyleDemoTemplateToggle[];
+/**
+ * The `@dereekb/dbx-web/style-demo` section group.
+ */
+declare const DBX_WEB_STYLE_DEMO_SECTION_GROUP: DbxStyleDemoSectionGroup;
+/**
+ * Registers the `@dereekb/dbx-web/style-demo` sections and style levers with the `<dbx-style-demo>` playground.
+ *
+ * Contributes the web section group and template toggles via their multi-providers, and seeds the
+ * {@link DbxStyleDemoStyleLoaderService} with the matching templates via an environment initializer.
+ *
+ * Pair with `provideDbxStyleDemo()` (the shell).
+ *
+ * @returns EnvironmentProviders contributing the web sections and levers.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+declare function provideDbxWebStyleDemo(): EnvironmentProviders;
+
+/**
+ * Configuration for {@link provideDbxStyleDemo}.
+ */
+interface ProvideDbxStyleDemoConfig {
+    /**
+     * Templates to seed the {@link DbxStyleDemoStyleLoaderService} with at construction time.
+     *
+     * Libraries typically register their own templates via their own provider (e.g. `provideDbxWebStyleDemo()`); this
+     * app-level seed is for one-off templates an app defines directly.
+     */
+    readonly templates?: Maybe<DbxStyleDemoStyleTemplate[]>;
+    /**
+     * When false, the {@link DbxStyleDemoControlsService} does not forward its active style levers into the
+     * `DbxStyleService` as a body supplement, so levers only repaint the playground subtree. Defaults to true.
+     */
+    readonly applyStylesToApp?: Maybe<boolean>;
+}
+/**
+ * Provides the `<dbx-style-demo>` showcase shell: the {@link DbxStyleDemoStyleLoaderService}, the
+ * {@link DbxStyleDemoControlsService}, and an optional seed config.
+ *
+ * Pair with `provideDbxWebStyleDemo()` (and the per-library plumbing providers) to register the sections and style levers.
+ *
+ * @param config - Optional configuration seeding the loader service with templates and toggling app-wide style forwarding.
+ * @returns EnvironmentProviders for the showcase shell.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+declare function provideDbxStyleDemo(config?: ProvideDbxStyleDemoConfig): EnvironmentProviders;
+
+export { DBX_STYLE_DEMO_CONTROLS_COMPONENT, DBX_STYLE_DEMO_CONTROLS_DETACH_KEY, DBX_STYLE_DEMO_SECTIONS_COMPONENT, DBX_STYLE_DEMO_SECTIONS_POPOVER_KEY, DBX_STYLE_DEMO_SECTION_GROUP, DBX_STYLE_DEMO_TEMPLATE_TOGGLE, DBX_WEB_STYLE_DEMO_SECTION_GROUP, DBX_WEB_STYLE_DEMO_TEMPLATES, DBX_WEB_STYLE_DEMO_TEMPLATE_TOGGLES, DbxStyleDemoButtonsSectionComponent, DbxStyleDemoCardsSectionComponent, DbxStyleDemoColorTemplatesSectionComponent, DbxStyleDemoColorTonesSectionComponent, DbxStyleDemoComponent, DbxStyleDemoControlsService, DbxStyleDemoControlsServiceConfig, DbxStyleDemoNavigationSectionComponent, DbxStyleDemoSectionRegistry, DbxStyleDemoShapeScaleSectionComponent, DbxStyleDemoStyleLoaderDirective, DbxStyleDemoStyleLoaderService, DbxStyleDemoStyleLoaderServiceConfig, DbxStyleDemoSurfacesSectionComponent, DbxStyleDemoTypeRolesSectionComponent, groupDbxStyleDemoTemplateToggles, isDbxStyleDemoStyleLoaderConfig, isDbxStyleDemoStyleTemplate, mergeDbxStyleDemoStyleTemplates, provideDbxStyleDemo, provideDbxStyleDemoSections, provideDbxStyleDemoTemplateToggles, provideDbxWebStyleDemo };
+export type { DbxStyleDemoConfig, DbxStyleDemoControls, DbxStyleDemoSection, DbxStyleDemoSectionGroup, DbxStyleDemoSectionId, DbxStyleDemoStyleLoaderConfig, DbxStyleDemoStyleLoaderInput, DbxStyleDemoStyleSet, DbxStyleDemoStyleTemplate, DbxStyleDemoStyleTemplateKey, DbxStyleDemoTemplateToggle, DbxStyleDemoTemplateToggleGroup, ProvideDbxStyleDemoConfig };