@lifecorner/angular-ui-kit 3.4.0 → 3.5.0

package/types/lifecorner-angular-ui-kit-hero.d.ts

@@ -0,0 +1,121 @@
+import * as i0 from "@angular/core";
+export type HeroColor = 'primary' | 'secondary' | 'neutral' | 'success' | 'info' | 'warning' | 'accent-orange' | 'accent-purple' | 'accent-violet';
+export type HeroSize = 'sm' | 'md' | 'lg';
+export type HeroVariant = 'default' | 'slim' | 'light';
+/**
+ * Width of the hero's content box.
+ * - `full`: the content runs to the hero's own padding (default, as before 3.4)
+ * - `lg`: from 1024 px the content sits on the `lc-container` `lg` page column
+ *   (1024 px minus its 48 px sides, so at most 928 px), centred, while the
+ *   background stays full-bleed
+ */
+export type HeroContentWidth = 'full' | 'lg';
+/**
+ * Hero component for prominent page headers with gradient backgrounds.
+ *
+ * Features:
+ * - Color gradient variants (primary, secondary, success, warning, info, neutral, accent-orange, accent-purple, accent-violet)
+ * - 3 visual variants: default (dark gradient), slim (compact banner), light (pastel gradient with dark text)
+ * - Size options (sm, md, lg)
+ * - Optional label text above the title
+ * - Configurable border radius
+ * - Content projection for body and footer sections
+ * - Footer slot for metadata, stats, or CTAs
+ * - Media slot (`[hero-media]`) for a visual: below the text on small screens,
+ *   beside it from 1024 px, never under the body's 85 % opacity
+ * - Content width `lg`: a full-bleed band whose text lines up with the page column
+ *
+ * @example
+ * ```html
+ * <lc-hero label="MY APP" title="Welcome" color="primary" variant="slim">
+ *   <p>Description text</p>
+ *   <div hero-footer>Status: Active</div>
+ * </lc-hero>
+ *
+ * <lc-hero title="Everything in view" borderRadius="none" contentWidth="lg">
+ *   <p>Description text</p>
+ *   <lc-card hero-media variant="elevated">…</lc-card>
+ * </lc-hero>
+ * ```
+ */
+export declare class HeroComponent {
+  /**
+   * Small uppercase label displayed above the title.
+   */
+  label: import("@angular/core").InputSignal<string | undefined>;
+  /**
+   * Main headline text.
+   */
+  title: import("@angular/core").InputSignal<string>;
+  /**
+   * Color theme for the gradient background.
+   * @default 'primary'
+   */
+  color: import("@angular/core").InputSignal<HeroColor>;
+  /**
+   * Size variant controlling padding and font sizes.
+   * @default 'md'
+   */
+  size: import("@angular/core").InputSignal<HeroSize>;
+  /**
+   * Border radius of the hero container.
+   * @default 'lg'
+   */
+  borderRadius: import("@angular/core").InputSignal<"sm" | "md" | "lg" | "none">;
+  /**
+   * Visual variant.
+   * - `default`: dark gradient with white text
+   * - `slim`: compact single-line banner
+   * - `light`: softer pastel gradient with dark text
+   * @default 'default'
+   */
+  variant: import("@angular/core").InputSignal<HeroVariant>;
+  /**
+   * Width of the content box. `lg` keeps the background full-bleed and, from
+   * 1024 px, puts the label, title, body, media and footer on the 1024 px page
+   * column (the `lc-container` `lg` content box), never closer to the edge than
+   * the size padding. Use it for a full-width band (`borderRadius="none"`) whose
+   * text should line up with the page content below.
+   * @default 'full'
+   */
+  contentWidth: import("@angular/core").InputSignal<HeroContentWidth>;
+  protected heroClasses: import("@angular/core").Signal<string>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<HeroComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<HeroComponent, "lc-hero", never, {
+    "label": {
+      "alias": "label";
+      "required": false;
+      "isSignal": true;
+    };
+    "title": {
+      "alias": "title";
+      "required": true;
+      "isSignal": true;
+    };
+    "color": {
+      "alias": "color";
+      "required": false;
+      "isSignal": true;
+    };
+    "size": {
+      "alias": "size";
+      "required": false;
+      "isSignal": true;
+    };
+    "borderRadius": {
+      "alias": "borderRadius";
+      "required": false;
+      "isSignal": true;
+    };
+    "variant": {
+      "alias": "variant";
+      "required": false;
+      "isSignal": true;
+    };
+    "contentWidth": {
+      "alias": "contentWidth";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, ["*", "[hero-media]", "[hero-footer]"], true, never>;
+}

package/types/lifecorner-angular-ui-kit-icon-names.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The canonical set of valid `lc-icon` names: every served Tabler icon plus
+ * every documented alias ({@link ICON_ALIASES}) and inlined icon.
+ * Stored space-joined and split at load to keep the bundle compact.
+ */
+export declare const ICON_NAMES: readonly string[];
+/**
+ * Whether `name` is a valid `lc-icon` name — i.e. a served Tabler icon, a
+ * documented alias ({@link ICON_ALIASES}), or an inlined icon.
+ *
+ * `lc-icon` uses it in development builds only, so production bundles leave
+ * the list out unless the app imports it.
+ *
+ * @example
+ * ```ts
+ * isValidIconName('flask');       // true  (Tabler)
+ * isValidIconName('x-mark');      // true  (Heroicon alias)
+ * isValidIconName('beaker');      // false (not a Tabler name — did you mean 'flask'?)
+ * ```
+ */
+export declare function isValidIconName(name: string): boolean;

package/types/lifecorner-angular-ui-kit-icon.d.ts

@@ -0,0 +1,260 @@
+import * as i0 from "@angular/core";
+export type IconVariant = 'outline' | 'solid';
+export type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Clears the warn-once-per-name registry. Only needed by unit tests that
+ * assert on console warnings across multiple cases.
+ * @internal
+ */
+export declare function resetIconWarnings(): void;
+/**
+ * Clears the shared per-path fetch cache. Only needed by unit tests, whose
+ * `HttpTestingController` is recreated per test.
+ * @internal
+ */
+export declare function resetIconCache(): void;
+/**
+ * Icon component - Tabler Icons wrapper for displaying SVG icons
+ *
+ * Features:
+ * - Signal-based reactive API
+ * - Support for outline and solid variants
+ * - Multiple size options (xs, sm, md, lg, xl)
+ * - Custom color support (CSS colors, variables)
+ * - Accessibility attributes (ARIA labels, decorative icons)
+ * - Inline SVGs for the common icons (a hand-picked set plus Tabler icons
+ *   inlined at build time, see {@link isInlineIconName}): no request, they
+ *   render offline and in prerendered HTML; looked up by the name as written,
+ *   then by its alias target
+ * - Dynamic SVG loading from Tabler Icons for everything else
+ * - Fail-loud on unknown names: a console warning (once per name, in dev AND
+ *   prod) + a visible placeholder (never a silent empty space). Development
+ *   builds check every name against {@link ICON_NAMES} / {@link isValidIconName}
+ *   and request **no** unknown name, because in SPA deployments the server
+ *   answers missing asset paths with the index.html fallback. Production
+ *   builds leave the ~5,000 names out of the bundle (3.5, AS-15): they check
+ *   a name only by its form, request a well-formed unknown name once per
+ *   page, and show the placeholder when the answer is not an icon. See
+ *   {@link ICON_ALIASES} for the supported Heroicon/Material aliases.
+ * - Fetched responses are validated before anything reaches the page: a
+ *   `text/html` or non-SVG response (e.g. the SPA index.html fallback) is
+ *   dropped, and an SVG is rebuilt from an allow-list — basic shapes (`g`,
+ *   `path`, `circle`, `ellipse`, `line`, `polyline`, `polygon`, `rect`,
+ *   `text`) with paint and geometry attributes. Scripts, event handlers,
+ *   references (`href`, `url(…)`) and anything else drop the icon, which
+ *   then shows the placeholder.
+ * - One request per asset path per page (shared cache, a 404 included); a
+ *   name change cancels the instance's pending load so a slow old response
+ *   never overwrites the newer icon; `size` / `color` / `decorative` /
+ *   `ariaLabel` re-decorate the rendered `<svg>` in place, without refetching.
+ *
+ * **Trusted Types** (3.5, AS-14): bundled icons go through one policy,
+ * `lc-icon`, created on the first icon render; it accepts only the kit's own
+ * SVG strings. If your Content Security Policy enforces Trusted Types, add
+ * `lc-icon` to its `trusted-types` directive (with two copies of the kit on
+ * one page, the second needs `'allow-duplicates'`). Fetched icons need no
+ * policy: they are rebuilt node by node from the allow-list above. When the
+ * page refuses the policy, bundled icons show the placeholder and the console
+ * says so once. No sanitizer bypass, no HTML binding.
+ *
+ * @example
+ * ```html
+ * <!-- Basic usage -->
+ * <lc-icon name="user" />
+ *
+ * <!-- With variant and size -->
+ * <lc-icon name="check" variant="solid" size="lg" />
+ *
+ * <!-- With custom color -->
+ * <lc-icon name="arrow-right" color="#FF5733" />
+ *
+ * <!-- With CSS variable color -->
+ * <lc-icon name="star" color="var(--color-primary-500)" />
+ *
+ * <!-- With accessibility label -->
+ * <lc-icon name="user" ariaLabel="User profile" />
+ *
+ * <!-- Decorative icon (hidden from screen readers) -->
+ * <lc-icon name="sparkles" [decorative]="true" />
+ *
+ * <!-- Strict: throw in dev when the name is unknown (catch typos in CI) -->
+ * <lc-icon name="beaker" [strict]="true" />
+ * ```
+ */
+export declare class IconComponent {
+  private readonly http;
+  private readonly doc;
+  /**
+   * Fetching needs a browser; the server renders inline icons and the
+   * placeholder (through the allow-list builder) and leaves fetched names
+   * empty — the client takes over on hydration.
+   */
+  private readonly isBrowser;
+  private readonly container;
+  /**
+   * Icon name from Tabler Icons library
+   * @example "user", "check", "arrow-right"
+   */
+  readonly name: import("@angular/core").InputSignal<string>;
+  /**
+   * Icon variant (outline or solid)
+   * @default "outline"
+   */
+  readonly variant: import("@angular/core").InputSignal<IconVariant>;
+  /**
+   * Icon size
+   * - xs: 16px
+   * - sm: 20px
+   * - md: 24px (default)
+   * - lg: 32px
+   * - xl: 40px
+   * @default "md"
+   */
+  readonly size: import("@angular/core").InputSignal<IconSize>;
+  /**
+   * Icon color
+   * Can be:
+   * - CSS color: "#FF5733", "rgb(255, 87, 51)"
+   * - CSS variable: "var(--color-primary-500)"
+   * - "currentColor" (default - inherits from parent)
+   * @default "currentColor"
+   */
+  readonly color: import("@angular/core").InputSignal<string>;
+  /**
+   * Accessible label for screen readers
+   * Required if icon has semantic meaning
+   */
+  readonly ariaLabel: import("@angular/core").InputSignal<string | undefined>;
+  /**
+   * Whether icon is purely decorative (hidden from screen readers)
+   * @default false
+   */
+  readonly decorative: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Strict mode. When `true` and the name is not a valid icon (see
+   * {@link isValidIconName}), the component **throws** in development mode
+   * instead of only warning — useful as a CI guard to catch typos/unknown
+   * names. No effect in production builds.
+   * @default false
+   */
+  readonly strict: import("@angular/core").InputSignal<boolean>;
+  /**
+   * What the container shows for the current name/variant. Loading writes
+   * here; the element and its decoration are derived below.
+   */
+  private readonly source;
+  /**
+   * A fresh `<svg>` for the current source, undecorated. It depends on the
+   * source only, so a change of `size`, `color`, `decorative` or `ariaLabel`
+   * re-decorates the same element instead of building a new one.
+   */
+  private readonly svgElement;
+  /**
+   * Computed path to SVG file
+   * @internal
+   */
+  readonly iconPath: import("@angular/core").Signal<string>;
+  /**
+   * Computed size in pixels
+   * @internal
+   */
+  readonly sizeInPixels: import("@angular/core").Signal<string>;
+  /**
+   * Computed CSS classes
+   * @internal
+   */
+  readonly computedClasses: import("@angular/core").Signal<string>;
+  /**
+   * Computed inline color style
+   * @internal
+   */
+  readonly colorStyle: import("@angular/core").Signal<string>;
+  constructor();
+  /**
+   * A known name whose asset can't be loaded stays quiet in development (as
+   * before: unit tests and offline work have no assets). Production can't
+   * tell it from a typo — the list isn't there — so it says so, once.
+   */
+  private warnLoadFailure;
+  static ɵfac: i0.ɵɵFactoryDeclaration<IconComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<IconComponent, "lc-icon", never, {
+    "name": {
+      "alias": "name";
+      "required": false;
+      "isSignal": true;
+    };
+    "variant": {
+      "alias": "variant";
+      "required": false;
+      "isSignal": true;
+    };
+    "size": {
+      "alias": "size";
+      "required": false;
+      "isSignal": true;
+    };
+    "color": {
+      "alias": "color";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "decorative": {
+      "alias": "decorative";
+      "required": false;
+      "isSignal": true;
+    };
+    "strict": {
+      "alias": "strict";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * Alias map for non-Tabler icon names.
+ *
+ * `lc-icon` serves the **Tabler** icon set, but components across the ecosystem
+ * frequently reference **Heroicon** (and a few Material Design) names, which use
+ * different identifiers. Each entry here maps such an alias to its Tabler
+ * equivalent so HTTP loading resolves correctly.
+ *
+ * This map is part of the public API so consumers can see exactly which
+ * non-Tabler names are supported (and lint against them). Every key is also
+ * included in {@link ICON_NAMES} as a valid `lc-icon` name.
+ *
+ * @see ICON_NAMES
+ * @see isValidIconName
+ */
+export declare const ICON_ALIASES: Readonly<Record<string, string>>;
+/**
+ * A valid `lc-icon` name.
+ *
+ * There are ~5000 valid names, so this is intentionally a broad `string` alias
+ * rather than a giant union type (which would bloat editors and builds). Prefer
+ * runtime validation via {@link isValidIconName}, or lint your usages against
+ * the {@link ICON_NAMES} array (also shipped as `icon-names.json`), both from
+ * `@lifecorner/angular-ui-kit/icon-names`.
+ */
+export type IconName = string;
+/**
+ * Whether `name` renders from markup shipped in the kit — no request, so it
+ * shows offline, at once and in prerendered HTML (3.3, gap G-7). Covers the
+ * hand-picked inline set, the Tabler icons inlined at build time (mail,
+ * users, settings, logout, key, chevron-right, …) and aliases that resolve
+ * to either. Use it to lint an app or a static site against icons that would
+ * be fetched.
+ *
+ * @example
+ * ```ts
+ * isInlineIconName('x-mark');           // true  (hand-picked, by its alias name)
+ * isInlineIconName('envelope');         // true  (alias of the inlined Tabler `mail`)
+ * isInlineIconName('anchor');           // false (fetched from the Tabler assets)
+ * isInlineIconName('robot', 'solid');   // false (Tabler has no filled robot)
+ * ```
+ */
+export declare function isInlineIconName(name: string, variant?: IconVariant): boolean;