@koobiq/components 20.4.1 → 21.0.0

package/types/koobiq-components-link.d.ts

@@ -0,0 +1,176 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, AfterViewChecked, Provider } from '@angular/core';
+import { KbqDefaultSizes } from '@koobiq/components/core';
+
+/** When the text of a link is underlined: always, only while the pointer is over the link, or never. */
+type KbqLinkUnderline = 'always' | 'hover' | 'none';
+/**
+ * Settings a whole application shares, rather than something a single link decides: how big links are, when
+ * they are underlined and whether visited ones stand out. Where a link leads and how it behaves stay on the
+ * link itself.
+ */
+type KbqLinkOptions = {
+    /** Size of a link: its typography and the gaps to its icons. */
+    size: KbqDefaultSizes;
+    /**
+     * When the text of a link and of a pseudo link is underlined. Unset, a link is always underlined and a pseudo
+     * link only on hover.
+     */
+    underline?: KbqLinkUnderline;
+    /** Whether a visited link is styled differently. */
+    useVisited: boolean;
+};
+/** Injection token holding the current {@link KbqLinkOptions}. */
+declare const KBQ_LINK_OPTIONS: InjectionToken<KbqLinkOptions>;
+/**
+ * Overrides the default link options within the given injector scope: the whole application from
+ * `bootstrapApplication`, or one subtree from the `providers` of a component or a route.
+ */
+declare function kbqLinkOptionsProvider(options: Partial<KbqLinkOptions>): Provider;
+/** Marks content to be projected before the text of a link, such as a leading icon. */
+declare class KbqLinkPrefix {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqLinkPrefix, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<KbqLinkPrefix, "[kbqLinkPrefix]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Marks content to be projected after the text of a link: a trailing icon, or the punctuation that ends a
+ * sentence, which takes the link color without the underline. It wraps to the next line together with the last
+ * word only.
+ */
+declare class KbqLinkSuffix {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqLinkSuffix, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<KbqLinkSuffix, "[kbqLinkSuffix]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Link of the design system. Applied to an `<a>` with a `href`, so that the browser keeps treating it as a
+ * link, or to any other element, which makes it a pseudo link that acts as a button. The component renders the
+ * text between the `kbqLinkPrefix` and `kbqLinkSuffix` content, and only the text is underlined.
+ */
+declare class KbqLink implements AfterViewChecked {
+    private readonly renderer;
+    private readonly destroyRef;
+    private readonly ngZone;
+    private readonly focusMonitor;
+    private readonly options;
+    private readonly nativeElement;
+    private readonly textElement;
+    /**
+     * `disabled` is valid on a `<button>`, but not on an `<a>` or a `<span>`, where it means nothing to
+     * assistive tech, so the state is exposed through ARIA there instead.
+     */
+    private readonly hostSupportsNativeDisabled;
+    /**
+     * The role written on the element in the template. Such an element owns its semantics and its keyboard, and
+     * the binding keeps the role in place. It is read from the template rather than from the element: on a
+     * hydrated page the element already carries the role this component rendered on the server.
+     */
+    private readonly declaredRole;
+    /**
+     * Whether a pseudo link may supply the button semantics itself: a `<button>` and a `<label>` are
+     * activatable on their own, and so is an element that declares a role in the template.
+     */
+    private readonly ownsPseudoSemantics;
+    /** A `<label>` is reached through its control, so it stays out of the tab order unless it declares a role. */
+    private readonly focusable;
+    /** Only an anchor can lead somewhere: on any other element the link is a pseudo link. */
+    private readonly anchor;
+    /** The text nodes trimmed at an edge of the text, with their data before, for one that leaves the edge. */
+    private readonly trimmedTexts;
+    /** Whether the link is disabled. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Effective disabled state, mirroring the `disabled` input. It stays writable because `kbqTooltip`
+     * accepts a link through `forDisabledComponent` and reads this signal to keep a tooltip reachable on a
+     * disabled link; the host bindings read it rather than the input so such a write still shows.
+     *
+     * @docs-private
+     */
+    readonly disabledSignal: _angular_core.WritableSignal<boolean>;
+    /**
+     * Tab order of the link: the `tabindex` written on the element, or 0. A disabled link is taken out of the tab
+     * order regardless of this value, and a `<label>` is left out of it: the control it labels is the one that
+     * takes the focus.
+     */
+    readonly tabIndex: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Whether an `<a>` is a pseudo link: a control without a `href` that looks like a link. Any other element is
+     * a pseudo link anyway. A pseudo link gets the `button` role and is activated with Enter and Space, unless
+     * the element is a `<button>` or a `<label>`, declares a role of its own in the template, or is taken out of
+     * the tab order with a negative `tabIndex`. A key that another directive on the element has already handled,
+     * as `kbqDropdownTriggerFor` does, is left to it.
+     */
+    readonly pseudo: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Whether the link leads outside the product. Adds the external link icon after the text. It does not set
+     * `target`: bind `target="_blank"` as well to open the page in a new tab.
+     */
+    readonly external: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When the text is underlined. Defaults to the app-wide {@link KBQ_LINK_OPTIONS}, and without one there to
+     * `always` for a link and `hover` for a pseudo link.
+     */
+    readonly underline: _angular_core.InputSignal<KbqLinkUnderline | undefined>;
+    /**
+     * Size of the link: its typography and the gaps to its icons. Defaults to the app-wide
+     * {@link KBQ_LINK_OPTIONS}.
+     */
+    readonly size: _angular_core.InputSignal<KbqDefaultSizes>;
+    /** Whether a visited link is styled differently. Defaults to the app-wide {@link KBQ_LINK_OPTIONS}. */
+    readonly useVisited: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * What to print after the link text when the page is printed. An empty string, which a valueless `print`
+     * attribute is, prints the `href` without its protocol and `www.`; any other string is printed as is. Unbound
+     * or `null`, nothing is printed.
+     */
+    readonly print: _angular_core.InputSignal<string | null | undefined>;
+    /** @docs-private */
+    protected readonly isPseudo: _angular_core.Signal<boolean>;
+    /** @docs-private */
+    protected readonly underlineMode: _angular_core.Signal<KbqLinkUnderline>;
+    /**
+     * Whether the pseudo link is a button of its own. One taken out of the tab order with a negative
+     * `tabIndex` is activated through something else - the file input of a file upload's label, for
+     * instance - and gets neither the role nor the keyboard.
+     */
+    private readonly actsAsButton;
+    /** @docs-private */
+    protected readonly role: _angular_core.Signal<string | null>;
+    /** @docs-private */
+    protected readonly nativeDisabledAttribute: _angular_core.Signal<true | null>;
+    /** @docs-private */
+    protected readonly ariaDisabledAttribute: _angular_core.Signal<true | null>;
+    /** @docs-private */
+    protected readonly hostTabIndex: _angular_core.Signal<number | null>;
+    constructor();
+    /**
+     * Angular collapses the whitespace that a formatted template leaves around the text to a single space
+     * instead of removing it. Inside the text that space would be underlined, widen the gap to an icon and
+     * let the suffix wrap away from the last word, so it is trimmed. The printed text is written here too: by
+     * now `routerLink` has set the `href`.
+     */
+    ngAfterViewChecked(): void;
+    /** Focuses the link. */
+    focus(): void;
+    /** The element the link is applied to. */
+    getHostElement(): HTMLElement;
+    private monitorFocus;
+    private activateOnEnterAndSpace;
+    private activate;
+    private blockActivationWhileDisabled;
+    private updatePrintedText;
+    private trimEdgeTextNodes;
+    private edgeTextNode;
+    private trimText;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqLink, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KbqLink, "[kbqLink]", ["kbqLink"], { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "pseudo": { "alias": "pseudo"; "required": false; "isSignal": true; }; "external": { "alias": "external"; "required": false; "isSignal": true; }; "underline": { "alias": "underline"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "useVisited": { "alias": "useVisited"; "required": false; "isSignal": true; }; "print": { "alias": "print"; "required": false; "isSignal": true; }; }, {}, never, ["[kbqLinkPrefix]", "*", "[kbqLinkSuffix]"], true, never>;
+}
+
+/** @docs-private */
+declare class KbqLinkModule {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqLinkModule, never>;
+    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<KbqLinkModule, never, [typeof KbqLink, typeof KbqLinkPrefix, typeof KbqLinkSuffix], [typeof KbqLink, typeof KbqLinkPrefix, typeof KbqLinkSuffix]>;
+    static ɵinj: _angular_core.ɵɵInjectorDeclaration<KbqLinkModule>;
+}
+
+export { KBQ_LINK_OPTIONS, KbqLink, KbqLinkModule, KbqLinkPrefix, KbqLinkSuffix, kbqLinkOptionsProvider };
+export type { KbqLinkOptions, KbqLinkUnderline };