@koobiq/components 20.4.2 → 21.0.0

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

@@ -0,0 +1,68 @@
+import * as _angular_core from '@angular/core';
+import { SafeHtml } from '@angular/platform-browser';
+
+/** Shape of the flag. `rectangle` keeps the default 3:2 ratio, `square`/`circle` expect a 1:1 source. */
+type KbqFlagShape = 'rectangle' | 'square' | 'circle';
+/** Inset shadow (hairline) that separates the flag from the background. */
+type KbqFlagShadow = 'inset' | 'none';
+
+/**
+ * Presentational wrapper for a consumer-provided country flag (inline `<svg>` or `<img>`).
+ * Decorates it with shape and shadow and applies the accessibility contract.
+ *
+ * The flag is either projected, or passed as markup through the `svg` input. Do not bind
+ * `[innerHTML]` on the host element — that write replaces whatever was projected into it.
+ *
+ * ```html
+ * <kbq-flag decorative><img src="…/AL.svg" alt="" /></kbq-flag> Albania
+ * ```
+ */
+declare class KbqFlag {
+    /**
+     * Shape of the flag. The flag is cropped to it, so `square`/`circle` are best fed a 1:1 source —
+     * a center crop of a rectangular flag can cut off meaningful elements. Defaults to `'rectangle'`.
+     */
+    readonly shape: _angular_core.InputSignal<KbqFlagShape>;
+    /**
+     * Proportions of the flag box, as a CSS `aspect-ratio` value (`4 / 3`, `1.5`). Set it for a source
+     * whose proportions differ from the shape — the flag is cropped to the box either way.
+     *
+     * It overrides the ratio the shape implies, so `shape="square"` with an `aspectRatio` is no longer
+     * square. Left unset, the ratio comes from the `--kbq-flag-aspect-ratio` token, which a plain class
+     * rule can still redefine for a whole group of flags at once.
+     */
+    readonly aspectRatio: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Inset hairline that keeps the flag distinct from the background. Its color adapts to the theme.
+     * Defaults to `'inset'`.
+     */
+    readonly shadow: _angular_core.InputSignal<KbqFlagShadow>;
+    /** Renders a neutral placeholder — use when no flag can be shown (unknown / invalid country code). */
+    readonly empty: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Flag markup rendered into a slot of its own, for flags that come from a package as a string.
+     * A plain string is sanitized, and Angular's sanitizer drops `<svg>` — pass an SVG through
+     * `DomSanitizer.bypassSecurityTrustHtml`, and only for markup known at build time.
+     */
+    readonly svg: _angular_core.InputSignal<string | SafeHtml | undefined>;
+    /** Marks the flag as decorative — hidden from screen readers (use when adjacent text is present). */
+    readonly decorative: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Accessible name for the flag. Use when the flag carries meaning and has no adjacent text.
+     * Without it the flag is hidden from screen readers, so a flag whose only name comes from the
+     * projected image (`alt`, `<title>`) has to repeat it here.
+     */
+    readonly label: _angular_core.InputSignal<string | undefined>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqFlag, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KbqFlag, "kbq-flag", ["kbqFlag"], { "shape": { "alias": "shape"; "required": false; "isSignal": true; }; "aspectRatio": { "alias": "aspectRatio"; "required": false; "isSignal": true; }; "shadow": { "alias": "shadow"; "required": false; "isSignal": true; }; "empty": { "alias": "empty"; "required": false; "isSignal": true; }; "svg": { "alias": "svg"; "required": false; "isSignal": true; }; "decorative": { "alias": "decorative"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+/** NgModule wrapper around the standalone `KbqFlag`, kept for consumers that still declare modules. */
+declare class KbqFlagModule {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqFlagModule, never>;
+    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<KbqFlagModule, never, [typeof KbqFlag], [typeof KbqFlag]>;
+    static ɵinj: _angular_core.ɵɵInjectorDeclaration<KbqFlagModule>;
+}
+
+export { KbqFlag, KbqFlagModule };
+export type { KbqFlagShadow, KbqFlagShape };