@cdevhub/ngx-tw 0.5.0 → 0.6.1

package/types/cdevhub-ngx-tw-tags-input-testing.d.ts

@@ -0,0 +1,135 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+
+/** Filters accepted by `TagsInputTagHarness.with`. */
+interface TagsInputTagHarnessFilters extends BaseHarnessFilters {
+    /** Match by the chip's visible label. */
+    text?: string | RegExp;
+}
+/**
+ * Harness for a single committed chip inside a `tw-tags-input`.
+ *
+ * Chips are rendered by composing `[twBadge]`, so that attribute is the host
+ * selector. Reach these through {@link TagsInputHarness.getTags} rather than
+ * locating them directly against a fixture — located from a document root the
+ * selector would also match every unrelated badge on the page.
+ */
+declare class TagsInputTagHarness extends ComponentHarness {
+    static hostSelector: string;
+    /**
+     * The chip's remove control. It is the only `<button>` a chip contains: the
+     * badge's own `dismissible` button is not enabled here, so this always
+     * resolves to the tags-input remove control.
+     */
+    private readonly removeButton;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: TagsInputTagHarnessFilters): HarnessPredicate<TagsInputTagHarness>;
+    /**
+     * The chip's visible label, trimmed. This is `tagLabel(tag)`, not the tag
+     * value — for object tags the two differ.
+     */
+    getText(): Promise<string>;
+    /**
+     * The remove control's accessible name (`Remove <label>`). Useful for
+     * asserting the control is announced, which is the only signal a screen
+     * reader gets for a chip.
+     */
+    getRemoveLabel(): Promise<string | null>;
+    /**
+     * Clicks the chip's remove control. The component restores focus to the
+     * neighbouring chip (or the text input when none remain), so the caller may
+     * assert focus immediately afterwards.
+     */
+    remove(): Promise<void>;
+}
+
+/** Filters accepted by `TagsInputHarness.with`. */
+interface TagsInputHarnessFilters extends BaseHarnessFilters {
+    /** Match by the control's accessible name (its `aria-label`). */
+    label?: string | RegExp;
+    /** Match disabled / enabled controls. */
+    disabled?: boolean;
+}
+/**
+ * Harness for `tw-tags-input`.
+ *
+ * The control renders committed tags as chips followed by a single text input;
+ * everything lives inside the `tw-tags-input` host, so no overlay handling is
+ * needed and the ordinary fixture loader is enough.
+ *
+ * Note where the ARIA lives: the host is a `role="group"`, which ARIA 1.2 does
+ * not allow to carry `aria-required` / `aria-invalid`, so those sit on the
+ * inner text input — the element that actually owns the pending value.
+ * {@link isRequired} and {@link isInvalid} read them from there;
+ * {@link isDisabled} reads `aria-disabled` from the group, which is allowed.
+ */
+declare class TagsInputHarness extends ComponentHarness {
+    static hostSelector: string;
+    private readonly textInput;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: TagsInputHarnessFilters): HarnessPredicate<TagsInputHarness>;
+    /** The control's accessible name, from `aria-label` when one is set. */
+    getLabel(): Promise<string | null>;
+    /** Whether the group reports `aria-disabled="true"`. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the text input reports `aria-required="true"`. */
+    isRequired(): Promise<boolean>;
+    /** Whether the text input reports `aria-invalid="true"`. */
+    isInvalid(): Promise<boolean>;
+    /**
+     * Every committed chip, in render order. Remove by index by indexing this
+     * array — `(await input.getTags())[1].remove()` — which is why no
+     * `removeTagAt(index)` exists.
+     */
+    getTags(filters?: TagsInputTagHarnessFilters): Promise<TagsInputTagHarness[]>;
+    /** The visible label of every committed chip, in render order. */
+    getTagTexts(): Promise<string[]>;
+    /** The in-progress (uncommitted) text currently in the input. */
+    getInputValue(): Promise<string>;
+    /**
+     * Types `text` into the input and commits it with Enter. Typing appends, so
+     * any pending text already in the input is committed along with it.
+     *
+     * Enter is the commit gesture only while `separatorKeys` contains `'Enter'`
+     * (the default). A control configured with, say, `[separatorKeys]="[';']"`
+     * commits through {@link typeInput} instead — `typeInput('alpha;')`.
+     *
+     * The commit may be dropped by the component (empty, duplicate, or `maxTags`
+     * reached); assert against {@link getTagTexts} rather than assuming it
+     * landed.
+     */
+    addTag(text: string): Promise<void>;
+    /**
+     * Types `text` into the input character by character, appending to whatever
+     * is already there. Use it to stage pending text that {@link addTag} would
+     * commit for you — reading it back, discarding it, or letting `addOnBlur`
+     * pick it up.
+     *
+     * A separator character in `text` does commit the text before it, but CDK's
+     * synthetic typing appends every character to the input regardless of the
+     * component's `preventDefault()`, so the separator itself is left behind in
+     * the input where a real browser swallows it. Commit with {@link addTag},
+     * and treat a trailing separator here as staging, not as a commit gesture.
+     */
+    typeInput(text: string): Promise<void>;
+    /**
+     * Removes the first chip whose label matches. Throws when nothing matches,
+     * rather than failing silently.
+     */
+    removeTag(text: string | RegExp): Promise<void>;
+    /**
+     * Discards the in-progress text with Escape — the control's own clear
+     * gesture. A no-op when the input is already empty. Does not touch committed
+     * chips.
+     */
+    clearInput(): Promise<void>;
+    /** Moves focus to the text input. */
+    focus(): Promise<void>;
+    /**
+     * Moves focus out of the control. This is the gesture that marks the control
+     * touched and, with `addOnBlur`, commits the pending text.
+     */
+    blur(): Promise<void>;
+}
+
+export { TagsInputHarness, TagsInputTagHarness };
+export type { TagsInputHarnessFilters, TagsInputTagHarnessFilters };

package/types/cdevhub-ngx-tw-tags-input.d.ts

@@ -59,7 +59,7 @@ declare class TagsInputComponent<T = string> extends FormFieldControl<T[]> imple
     readonly disabledInput: _angular_core.InputSignal<boolean>;
     /** Marks the control as required. Mirrored to the input's `aria-required`. Also inferred from `Validators.required` on a bound control. Defaults to `false`. */
     readonly requiredInput: _angular_core.InputSignal<boolean>;
-    /** Placeholder shown in the text input only while there are no chips and the input is empty. */
+    /** Placeholder shown in the text input only while there are no chips and the input is empty. Defaults to `undefined`. */
     readonly placeholder: _angular_core.InputSignal<string | undefined>;
     /** Keys that commit the in-progress text as a tag. Each entry is a `KeyboardEvent.key` value (`'Enter'`) or a single separator character (`','`). Single-character separators also split pasted text. Defaults to `['Enter', ',']`. */
     readonly separatorKeys: _angular_core.InputSignal<readonly string[]>;
@@ -75,19 +75,30 @@ declare class TagsInputComponent<T = string> extends FormFieldControl<T[]> imple
     readonly tagLabel: _angular_core.InputSignal<TwTagLabelFn<T>>;
     /** Equality comparator used for dedup when `allowDuplicates` is false. Defaults to `Object.is` (reference / value identity). String tags dedupe case-sensitively by default; pass `(a, b) => a.toLowerCase() === b.toLowerCase()` for case-insensitive dedup. */
     readonly compareWith: _angular_core.InputSignal<TwTagCompareFn<T>>;
-    /** Applied to the text input for labeling and identification only; does not submit the tag array via native (non-Angular) form posting. */
+    /** Applied to the text input for labeling and identification only; does not submit the tag array via native (non-Angular) form posting. Defaults to `undefined`. */
     readonly name: _angular_core.InputSignal<string | undefined>;
     /** Id on the host element. Auto-generated as `tw-tags-input-N` when not provided. Used by the form-field's `<label for>` association. */
     readonly idInput: _angular_core.InputSignal<string | undefined>;
-    /** Accessible name applied to the control when no visible label is wired. Mirrored to `aria-label`. */
+    /** Accessible name applied to the control when no visible label is wired. Mirrored to `aria-label`. Defaults to `undefined`. */
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that labels the control. Mirrored to `aria-labelledby`. */
+    /** ID of an external element that labels the control. Mirrored to `aria-labelledby`. Defaults to `undefined`. */
     readonly ariaLabelledby: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that describes the control. Form-field merges its hint / error ids alongside. */
+    /** ID of an external element that describes the control. Form-field merges its hint / error ids alongside. Defaults to `undefined`. Alias: `aria-describedby`. */
     readonly ariaDescribedby: _angular_core.InputSignal<string | undefined>;
     /** Per-instance override of the {@link ErrorStateMatcher}. When omitted, uses the `TW_ERROR_STATE_MATCHER` token's value. */
     readonly errorStateMatcher: _angular_core.InputSignal<ErrorStateMatcher | undefined>;
-    /** Fires when the tag array changes through user interaction (add, remove, clear). Emits a fresh array reference. Does not fire on `writeValue`. */
+    /**
+     * Fires when the tag array changes through user interaction (add, remove,
+     * clear). Emits a fresh array reference. Does **not** fire on `writeValue` /
+     * `FormControl.setValue` / `ngModel`.
+     *
+     * This is a hand-written, user-gesture-only output. The control exposes no
+     * `value` input and therefore no two-way binding, so — unlike
+     * `tw-checkbox` / `tw-switch` / `tw-radio-group`, where `(valueChange)` /
+     * `(checkedChange)` is minted by a `model()` and fires on programmatic writes
+     * too — there is no any-change channel here. Observe programmatic writes
+     * through the bound form control's own `valueChanges`.
+     */
     readonly valueChange: _angular_core.OutputEmitterRef<T[]>;
     /** Fires when a tag is committed via Enter, a separator key, paste, or `addTag()`. Does not fire for dropped duplicates, blocked-by-max commits, empty commits, or `writeValue`. */
     readonly tagAdded: _angular_core.OutputEmitterRef<TwTagAddedEvent<T>>;
@@ -98,10 +109,14 @@ declare class TagsInputComponent<T = string> extends FormFieldControl<T[]> imple
     private readonly elementRef;
     private readonly destroyRef;
     private readonly ngControl;
-    private readonly parentForm;
-    private readonly parentFormGroup;
-    private readonly defaultMatcher;
     private readonly formField;
+    /**
+     * Optional so a consumer that never imports `BidiModule` still gets a working
+     * control — chip navigation falls back to LTR when the token is absent. Read
+     * imperatively inside the keydown handlers; nothing here needs to re-render
+     * on a direction change.
+     */
+    private readonly directionality;
     private readonly textInputRef;
     private readonly removeButtons;
     private onChange;
@@ -113,8 +128,8 @@ declare class TagsInputComponent<T = string> extends FormFieldControl<T[]> imple
     protected readonly activeChipIndex: _angular_core.WritableSignal<number | null>;
     private readonly cvaDisabled;
     private readonly _focused;
-    private readonly _ngControlRev;
-    private readonly _formSubmitRev;
+    /** @internal Shared `errorState` / `required` / `errors` derivation — see `wireErrorState`. */
+    private readonly errorWiring;
     private readonly describedByIdsSignal;
     private readonly labelledByIdsSignal;
     /** Nonce bumped only on explicit focus intent — keeps the focus effect from stealing focus on unrelated renders. */

package/types/cdevhub-ngx-tw-textarea.d.ts

@@ -33,7 +33,8 @@ type TwTextareaResize = 'none' | 'vertical' | 'both';
  */
 declare class TextareaDirective extends InputDirective {
     private readonly cdkAutosize;
-    /** Density of a standalone textarea. Maps to the inline-padding + font scale (`xs` … `xl`). Ignored inside a `<tw-form-field>` — the wrapper's `size` carries density. Defaults to `'md'`. */
+    private readonly parentFormField;
+    /** Density of a standalone textarea. Maps to the inline-padding + font scale (`xs` … `xl`) and to a `min-h-*` floor on the control-height scale (24/32/36/44/48px) — a floor, not a fixed height, because a textarea must grow with its content. The floor is dropped while `autosize` is on (CDK owns the height then; `minRows` is the floor). Ignored inside a `<tw-form-field>` — the wrapper's `size` carries density. Defaults to `'md'`. */
     readonly size: _angular_core.InputSignal<TwSize>;
     /** Grows the textarea with its content (composed from CDK's `CdkTextareaAutosize`). When `true` the user-resize handle is forced off — autosize owns the height. Defaults to `false`. */
     readonly autosize: _angular_core.InputSignalWithTransform<boolean, unknown>;
@@ -49,7 +50,7 @@ declare class TextareaDirective extends InputDirective {
     readonly maxLength: _angular_core.InputSignalWithTransform<number | undefined, unknown>;
     /** Current value length, updates on every `input` event. Wire `<span twHint align="end">{{ ta.valueLength() }} / {{ ta.maxLength() }}</span>` for a character counter. */
     readonly valueLength: Signal<number>;
-    /** @internal Textarea-specific Tailwind classes (resize axis). Combined with the inherited `classes()` in the host `[class]` binding. */
+    /** @internal Textarea-specific Tailwind classes (resize axis + control-height floor). Combined with the inherited `classes()` in the host `[class]` binding — the two strings never emit conflicting utilities, so concatenating them needs no cross-config merge. */
     readonly textareaClasses: Signal<string>;
     constructor();
     /** Triggers a CDK autosize recalculation. Useful after programmatic value changes that bypass the native `(input)` event (e.g., clipboard write APIs). No-op when `autosize` is `false`. */

package/types/cdevhub-ngx-tw-theme.d.ts

@@ -1,84 +1,195 @@
 import * as _angular_core from '@angular/core';
 import { OnDestroy, InjectionToken, EnvironmentProviders } from '@angular/core';
 
-/** The user-selectable theme. `'system'` defers to the OS `prefers-color-scheme` setting. */
-type TwTheme = 'light' | 'dark' | 'high-contrast' | 'system';
-/** The theme actually applied to the DOM after resolving `'system'` against the OS preference. */
-type TwResolvedTheme = 'light' | 'dark' | 'high-contrast';
+/**
+ * The user-selectable theme. `'system'` defers to the OS, resolving
+ * `prefers-color-scheme` and `prefers-contrast` as two independent axes: dark
+ * plus increased contrast lands on `'high-contrast-dark'`, light plus increased
+ * contrast on `'high-contrast'`.
+ */
+type TwTheme = 'light' | 'dark' | 'high-contrast' | 'high-contrast-dark' | 'system';
+/**
+ * The theme actually applied to the DOM after resolving `'system'` against the
+ * OS preference.
+ *
+ * The two axes are appearance (light / dark) and contrast (normal / increased),
+ * so the four values are their product: `'high-contrast'` is the light-based
+ * increased-contrast scheme and `'high-contrast-dark'` the dark-based one.
+ */
+type TwResolvedTheme = 'light' | 'dark' | 'high-contrast' | 'high-contrast-dark';
 /** Ordered list of every {@link TwTheme} value, used by `cycleTheme()` and for UI iteration. */
-declare const TW_THEMES: readonly ["light", "dark", "high-contrast", "system"];
+declare const TW_THEMES: readonly ["light", "dark", "high-contrast", "high-contrast-dark", "system"];
 /** Ordered list of every {@link TwResolvedTheme} value (i.e. {@link TW_THEMES} minus `'system'`). */
-declare const TW_RESOLVED_THEMES: readonly ["light", "dark", "high-contrast"];
-/** Runtime configuration for {@link provideTheme}; controls storage, attribute name, target element, and default. */
+declare const TW_RESOLVED_THEMES: readonly ["light", "dark", "high-contrast", "high-contrast-dark"];
+/**
+ * Runtime configuration for {@link provideTheme}; controls storage, attribute
+ * name, target element, and default.
+ *
+ * Every member is optional. This interface only ever reaches consumers through
+ * `provideTheme(config?: Partial<TwThemeConfig>)`, which fills each unset key
+ * from {@link DEFAULT_TW_THEME_CONFIG} — so a consumer holding a config object
+ * typed as `TwThemeConfig` must not be forced to restate keys they do not
+ * override, and adding a member in a future minor must not break them. The
+ * resolved value handed to {@link TW_THEME_CONFIG} is `Required<TwThemeConfig>`.
+ */
 interface TwThemeConfig {
     /** The default theme when no preference is stored. Defaults to `'system'`. */
-    defaultTheme: TwTheme;
-    /** localStorage key for persisting theme preference. Defaults to `'ngx-tw-theme'`. */
-    storageKey: string;
+    defaultTheme?: TwTheme;
+    /**
+     * localStorage key for persisting an explicit theme choice. Defaults to
+     * `'ngx-tw-theme'`. Only `setTheme()` / `cycleTheme()` write it — providing
+     * the service never does.
+     */
+    storageKey?: string;
     /** The HTML attribute written to the target element. Defaults to `'data-theme'`. */
-    attribute: string;
+    attribute?: string;
     /** Which element receives the theme attribute. Defaults to `'documentElement'`. */
-    target: 'documentElement' | 'body';
+    target?: 'documentElement' | 'body';
 }
-/** Composite snapshot of `ThemeService` state — selected, resolved, system, and boolean flags. */
+/**
+ * Composite snapshot of `ThemeService` state — selected, resolved, system, and
+ * boolean flags.
+ *
+ * The three flags are **not** mutually exclusive: `'high-contrast-dark'` sets
+ * both {@link isDark} and {@link isHighContrast}, because it is dark *and*
+ * high contrast. Branch on {@link resolvedTheme} when you need one case.
+ */
 interface TwThemeState {
     /** The user-selected theme — may be `'system'`. */
     readonly theme: TwTheme;
     /** The theme actually applied to the DOM — never `'system'`. */
     readonly resolvedTheme: TwResolvedTheme;
-    /** The OS color-scheme preference detected via `prefers-color-scheme`. */
+    /** The OS appearance preference detected via `prefers-color-scheme` and `prefers-contrast`. */
     readonly systemTheme: TwResolvedTheme;
-    /** True when {@link resolvedTheme} is `'dark'`. */
+    /** True when {@link resolvedTheme} is a dark scheme — `'dark'` or `'high-contrast-dark'`. */
     readonly isDark: boolean;
-    /** True when {@link resolvedTheme} is `'light'`. */
+    /** True when {@link resolvedTheme} is exactly `'light'`; the light-based `'high-contrast'` does not set it. */
     readonly isLight: boolean;
-    /** True when {@link resolvedTheme} is `'high-contrast'`. */
+    /** True when {@link resolvedTheme} is an increased-contrast scheme — `'high-contrast'` or `'high-contrast-dark'`. */
     readonly isHighContrast: boolean;
 }
-/** Built-in defaults merged under any user-provided {@link TwThemeConfig} by `provideTheme()`. */
-declare const DEFAULT_TW_THEME_CONFIG: TwThemeConfig;
+/**
+ * Built-in defaults merged under any user-provided {@link TwThemeConfig} by
+ * `provideTheme()`. Typed `Required<TwThemeConfig>` so readers keep a
+ * non-optional `string` / `TwTheme` for every field even though the interface
+ * itself is all-optional.
+ */
+declare const DEFAULT_TW_THEME_CONFIG: Required<TwThemeConfig>;
 
 /**
  * Stateful runtime service that owns the active theme, reacts to OS
- * `prefers-color-scheme` changes, persists the user selection to
- * `localStorage`, and writes the resolved theme onto the configured DOM
- * target as a `data-theme` attribute.
+ * `prefers-color-scheme` / `prefers-contrast` changes, persists an explicit
+ * user selection to `localStorage`, and writes the resolved theme onto the
+ * configured DOM target as a `data-theme` attribute.
  *
  * The selected {@link theme} may be `'system'` (defer to the OS); the
  * {@link resolvedTheme} computed from it is always one of `'light'`,
- * `'dark'`, or `'high-contrast'` — never `'system'`. Register via
- * {@link provideTheme} in the app's environment providers.
+ * `'dark'`, `'high-contrast'`, or `'high-contrast-dark'` — never `'system'`.
+ * Register via
+ * {@link provideTheme} in the app's environment providers; `provideTheme`
+ * also constructs the service at bootstrap, so injecting it is only needed
+ * to read or change the theme.
+ *
+ * Storage is written **only** by {@link setTheme} / {@link cycleTheme}.
+ * Merely providing the service never touches `localStorage`, so the
+ * configured `defaultTheme` keeps applying until the user actually picks
+ * something, and apps under a storage-consent flow can provide the service
+ * before consent is granted.
  */
 declare class ThemeService implements OnDestroy {
     private readonly config;
     private readonly document;
     private readonly isBrowser;
     private readonly ngZone;
-    private mediaQuery;
+    private darkQuery;
+    private contrastQuery;
     private readonly mediaListener;
     /** The user-selected theme (may be `'system'`). */
     readonly theme: _angular_core.WritableSignal<TwTheme>;
-    /** The OS color scheme preference. */
+    /** The OS appearance preference — `prefers-color-scheme` plus `prefers-contrast`. */
     readonly systemTheme: _angular_core.WritableSignal<TwResolvedTheme>;
     /** The resolved theme actually applied to the DOM (never `'system'`). */
     readonly resolvedTheme: _angular_core.Signal<TwResolvedTheme>;
-    /** True when the resolved theme is `'dark'`. */
+    /**
+     * True when the resolved theme is a **dark** scheme — `'dark'` or
+     * `'high-contrast-dark'`.
+     *
+     * It answers the appearance question, not "which scheme": the canonical use
+     * is picking a colour that has to sit on the page background (a chart grid,
+     * a canvas fill), and dark high contrast needs the dark answer there just as
+     * much as plain dark does. It is therefore **not** mutually exclusive with
+     * {@link isHighContrast}; branch on {@link resolvedTheme} for one case.
+     */
     readonly isDark: _angular_core.Signal<boolean>;
-    /** True when the resolved theme is `'light'`. */
+    /**
+     * True when the resolved theme is exactly `'light'`.
+     *
+     * Deliberately narrower than {@link isDark}'s mirror image: the light-based
+     * `'high-contrast'` does **not** set it, because widening it would change
+     * what a shipped scheme reports to consumers already reading this flag.
+     * Use `!isDark()` for the appearance question.
+     */
     readonly isLight: _angular_core.Signal<boolean>;
-    /** True when the resolved theme is `'high-contrast'`. */
+    /**
+     * True when the resolved theme is an **increased-contrast** scheme —
+     * `'high-contrast'` or `'high-contrast-dark'`.
+     *
+     * It answers the contrast question, so it can be true at the same time as
+     * {@link isDark}.
+     */
     readonly isHighContrast: _angular_core.Signal<boolean>;
     /** Snapshot of the full theme state — selected, resolved, system, and boolean flags. */
     readonly state: _angular_core.Signal<TwThemeState>;
     constructor();
-    /** Sets the selected theme. Pass `'system'` to follow the OS preference. */
+    /**
+     * Sets the selected theme and persists it. Pass `'system'` to follow the OS
+     * preference.
+     *
+     * This is the only entry point that writes to `localStorage` — see the note
+     * on the class.
+     */
     setTheme(theme: TwTheme): void;
-    /** Advances the selected theme to the next entry in {@link TW_THEMES}, wrapping around. */
+    /** Advances the selected theme to the next entry in {@link TW_THEMES}, wrapping around, and persists it. */
     cycleTheme(): void;
-    /** Writes the configured theme attribute onto an arbitrary element — used to scope themes to a subtree. */
+    /**
+     * Writes the configured theme attribute onto an arbitrary element, scoping
+     * that subtree to the given theme.
+     *
+     * Each of the four schemes ships an element-agnostic `[data-theme=…]` block
+     * (`_light.css`, `_dark.css`, `_high-contrast.css`,
+     * `_high-contrast-dark.css`), so the tokens really do re-resolve on the
+     * element and cascade into its descendants — including back to `'light'`
+     * from inside a dark page.
+     *
+     * Caveat: those CSS blocks key off the literal `data-theme` attribute. If
+     * `provideTheme({ attribute })` renamed it, this method writes the renamed
+     * attribute and the shipped stylesheet will not react — a custom attribute
+     * only works with matching custom CSS.
+     */
     applyToElement(element: HTMLElement, theme: TwResolvedTheme): void;
     ngOnDestroy(): void;
     private loadInitialTheme;
+    /**
+     * Resolves `'system'` against the OS.
+     *
+     * The two preferences are treated as independent axes and composed, not
+     * ranked: `prefers-color-scheme` picks the appearance and
+     * `prefers-contrast: more` picks the contrast, giving the full 2×2 —
+     * `light` / `dark` / `high-contrast` / `high-contrast-dark`.
+     *
+     * This is only correct because the library ships **both** high-contrast
+     * ramps. While `_high-contrast.css` was the only one, contrast had to be
+     * suppressed whenever the OS also asked for dark, or a user running dark +
+     * increased contrast — a common pairing — would have been moved from a dark
+     * surface onto a white one. `_high-contrast-dark.css` removed that
+     * constraint, so the ranking is gone; if a future change ever drops one of
+     * the two ramps, this method has to go back to ranking them.
+     *
+     * Both queries are minted here (not in the constructor) because the
+     * `systemTheme` field initialiser calls this before the constructor body
+     * runs; the constructor then attaches `change` listeners to the same two
+     * objects, so the resolution stays live rather than read-once.
+     */
     private detectSystemTheme;
     private applyToDocument;
     private persistTheme;
@@ -87,20 +198,115 @@ declare class ThemeService implements OnDestroy {
 }
 
 declare class ThemeDirective {
-    /** Scopes a subtree to a specific resolved theme by writing `data-theme` on the host. Required. */
+    /**
+     * Scopes a subtree to a specific resolved theme by writing `data-theme` on
+     * the host. Required.
+     *
+     * Works in every direction: each of the four schemes ships an
+     * element-agnostic `[data-theme="…"]` block (`_light.css`, `_dark.css`,
+     * `_high-contrast.css`, `_high-contrast-dark.css`), so a `'light'` pane
+     * inside a dark page re-resolves the tokens rather than inheriting the
+     * ancestor's.
+     *
+     * The attribute name is the literal `data-theme` that the shipped CSS keys
+     * off — it deliberately ignores `provideTheme({ attribute })`, since a
+     * renamed attribute matches none of those blocks.
+     */
     readonly twTheme: _angular_core.InputSignal<TwResolvedTheme>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ThemeDirective, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ThemeDirective, "[twTheme]", never, { "twTheme": { "alias": "twTheme"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-/** Injection token carrying the resolved {@link TwThemeConfig} (storage key, attribute, target element, default theme). */
-declare const THEME_CONFIG: InjectionToken<TwThemeConfig>;
 /**
- * Registers {@link ThemeService} and a {@link THEME_CONFIG} value built by
- * merging `config` over {@link DEFAULT_TW_THEME_CONFIG}. Call once in the
- * app's environment providers.
+ * Injection token carrying the resolved {@link TwThemeConfig} (storage key,
+ * attribute, target element, default theme).
+ *
+ * The value is `Required<TwThemeConfig>`: `TwThemeConfig`'s members are
+ * optional so consumers can pass a partial config, but `provideTheme` fills
+ * every key from {@link DEFAULT_TW_THEME_CONFIG} before providing it. Injectors
+ * therefore still read a non-optional field for each setting, exactly as
+ * before this token's type was tightened.
+ */
+declare const TW_THEME_CONFIG: InjectionToken<Required<TwThemeConfig>>;
+/**
+ * @deprecated Renamed to {@link TW_THEME_CONFIG} for consistency with every
+ * other ngx-tw injection token. This is the *same token instance*, not a copy —
+ * providing under either name and injecting under the other resolves — so the
+ * rename is safe to adopt incrementally. Removed in the next major.
+ */
+declare const THEME_CONFIG: InjectionToken<Required<TwThemeConfig>>;
+/**
+ * Registers {@link ThemeService}, a {@link TW_THEME_CONFIG} value built by merging
+ * `config` over {@link DEFAULT_TW_THEME_CONFIG}, and an environment initializer
+ * that constructs the service at bootstrap. Call once in the app's environment
+ * providers.
+ *
+ * The initializer is what makes the call self-sufficient. Everything that
+ * applies a theme lives in `ThemeService`'s field initialisers and constructor
+ * effect, so without it the stored preference was read — and `data-theme`
+ * written — only once something happened to `inject(ThemeService)`. An app
+ * whose theme toggle sits in a lazily-loaded route therefore rendered every
+ * other route with no `data-theme` at all, silently falling back to the
+ * `prefers-color-scheme` CSS branch; the failure looked intermittent because
+ * it disappeared whenever the stored choice agreed with the OS. Injecting the
+ * service yourself is still supported and is idempotent.
+ *
+ * Keys explicitly set to `undefined` are dropped before merging. Root
+ * `tsconfig.json` does not set `exactOptionalPropertyTypes`, so
+ * `provideTheme({ storageKey: env.themeKey })` type-checks even when
+ * `env.themeKey` is `string | undefined` — and a plain spread would then write
+ * `undefined` into a field `TwThemeConfig` types as `string`, making
+ * `ThemeService` persist under the literal `localStorage` key `"undefined"`
+ * (and, for `attribute`, call `setAttribute("undefined", …)`).
+ *
+ * Providing the service does **not** write to `localStorage`; only an explicit
+ * `setTheme()` / `cycleTheme()` does. For a flash-free first paint when the
+ * stored choice disagrees with the OS, pair this with
+ * {@link TW_THEME_BOOTSTRAP_SCRIPT} in `index.html`.
  */
 declare function provideTheme(config?: Partial<TwThemeConfig>): EnvironmentProviders;
 
-export { DEFAULT_TW_THEME_CONFIG, THEME_CONFIG, TW_RESOLVED_THEMES, TW_THEMES, ThemeDirective, ThemeService, provideTheme };
+/**
+ * Body of an inline `<head>` script that applies a previously persisted theme
+ * before the app bundle runs, eliminating the flash of the wrong theme on
+ * reload.
+ *
+ * `ThemeService` cannot cover this case: it is JavaScript in the application
+ * bundle, so the browser has already painted by the time it writes
+ * `data-theme` — and `provideTheme`'s environment initializer does not change
+ * that. The CSS `@media (prefers-color-scheme: dark)` fallback covers users
+ * who never chose a theme; the flash is what an *explicit* choice that
+ * disagrees with the OS looks like — light chosen on a dark machine, or
+ * either high-contrast scheme chosen on a machine not already asking for
+ * increased contrast (the CSS has a `prefers-color-scheme` branch but
+ * deliberately no `prefers-contrast` one, so neither contrast scheme is
+ * reachable without an explicit `data-theme`).
+ *
+ * The string is built from {@link DEFAULT_TW_THEME_CONFIG}, so the storage key
+ * and attribute cannot drift from what `ThemeService` actually uses — that
+ * drift is the reason this ships as code rather than as a README snippet
+ * alone. Copy the literal script into `index.html`, or interpolate this
+ * constant during an SSR / index transform:
+ *
+ * ```html
+ * <head>
+ *   <script>try{var t=localStorage.getItem('ngx-tw-theme');if(t&&t!=='system')document.documentElement.setAttribute('data-theme',t)}catch(e){}</script>
+ * </head>
+ * ```
+ *
+ * Notes on the behaviour it deliberately does *not* have:
+ * - A stored `'system'` writes nothing, so the CSS `prefers-color-scheme`
+ *   fallback keeps deciding — which is exactly what `'system'` means.
+ * - It assumes the default `target: 'documentElement'`. A `<head>` script runs
+ *   before `<body>` exists, so `target: 'body'` cannot be bootstrapped this
+ *   way.
+ * - If you overrode `storageKey` or `attribute` via `provideTheme`, adapt the
+ *   literal snippet to match; this constant only encodes the defaults.
+ * - It is dependency-free and wrapped in `try`/`catch`, so a browser with
+ *   storage blocked falls through to the CSS behaviour instead of throwing
+ *   before the app loads.
+ */
+declare const TW_THEME_BOOTSTRAP_SCRIPT: string;
+
+export { DEFAULT_TW_THEME_CONFIG, THEME_CONFIG, TW_RESOLVED_THEMES, TW_THEMES, TW_THEME_BOOTSTRAP_SCRIPT, TW_THEME_CONFIG, ThemeDirective, ThemeService, provideTheme };
 export type { TwResolvedTheme, TwTheme, TwThemeConfig, TwThemeState };