@acorex/core 22.1.0-next.9 → 22.1.0

package/theme-builder/README.md

@@ -0,0 +1,53 @@
+# @acorex/core/theme-builder
+
+Secondary entry point of `@acorex/core`. Import from `@acorex/core/theme-builder`.
+
+Generate a complete ACoreX theme CSS file from a flat map of role seed colors.
+
+## Usage
+
+```ts
+import { createTheme } from '@acorex/core/theme-builder';
+
+// Full theme with defaults for omitted roles
+const { css } = createTheme();
+
+// Custom theme — only specify the roles you want to override
+const { css: brandedCss, palette } = createTheme({
+  primary: '#2b7fff',
+  secondary: '#6a7282',
+  success: '#00bc7d',
+  warning: '#fd9a00',
+  danger: '#ff2056',
+  surface: '#c2c2c2',
+  accent: '#06b6d4',
+});
+
+// Write css to theme.css in your app
+```
+
+## Role colors
+
+Supported roles: `primary`, `secondary`, `success`, `warning`, `danger`, `surface`, `accent`, `accent1`–`accent6`.
+
+Each provided color is applied to both light and dark modes. Dark shades are derived automatically. Omitted roles use the packaged default seeds.
+
+## Options
+
+```ts
+createTheme(colors, {
+  /** 'file' (default) — complete stylesheet with :root, .ax-dark, and Tailwind layer */
+  target: 'file',
+  /** 'preview' — scoped CSS variables for live preview injection */
+  target: 'preview',
+  scope: { light: ':root', dark: '.ax-dark' },
+  roles: ['primary', 'secondary'], // preview only: limit emitted roles
+});
+```
+
+## Return value
+
+`createTheme` returns:
+
+- `css` — the generated stylesheet string
+- `palette` — generated shade scales (`50`–`950`, `on`, `on-contrast`) for light and dark modes

package/types/acorex-core-date-time.d.ts

@@ -411,6 +411,11 @@ declare class AXSolarHijriCalendar extends AXCalendar {
     monthOfYear(date: Date): number;
     add(date: Date, unit: TimeUnit, amount: number): AXDateTime;
     set(date: Date, unit: TimeUnit, value: number): AXDateTime;
+    /**
+     * Builds a Date from converted civil Y/M/D while keeping the original time.
+     * Assigning year/month/day on an existing Date sequentially overflows (e.g. Aug 31 → Feb).
+     */
+    private withCivilDate;
     startOf(date: Date, unit: TimeUnit): AXDateTime;
     endOf(date: Date, unit: TimeUnit): AXDateTime;
     parse(value: string): AXDateTime;

package/types/acorex-core-locale.d.ts

@@ -34,6 +34,8 @@ interface AXLocaleProfile {
         week: {
             startsOn: number;
             weekends: number[];
+            /** Number of characters shown for weekday headers in calendar views (e.g. 1 for fa, 2 for en). */
+            weekdayLabelLength: number;
         };
         clock: {
             format24Hour: boolean;

package/types/acorex-core-theme-builder.d.ts

@@ -0,0 +1,42 @@
+type AXThemeBuilderColors = 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'surface' | 'accent' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6';
+type AXThemeBuilderColorVariants = '50' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | '950' | 'on' | 'on-contrast';
+type AXThemeBuilderPalette = Record<AXThemeBuilderColors, Record<AXThemeBuilderColorVariants, string>>;
+type AXThemeBuilderFullPalette = {
+    light: AXThemeBuilderPalette;
+    dark: AXThemeBuilderPalette;
+};
+type AXThemeBuilderBaseColors = {
+    light: Record<AXThemeBuilderColors, string>;
+    dark: Record<AXThemeBuilderColors, string>;
+};
+
+type AXThemeColors = Partial<Record<AXThemeBuilderColors, string>>;
+interface AXCreateThemeOptions {
+    /** 'file' (default) emits a complete stylesheet with :root/.ax-dark plus the Tailwind layer.
+     *  'preview' emits variables only, scoped to `scope`, for injecting into a live page. */
+    target?: 'file' | 'preview';
+    /** Selectors used when target is 'preview'. */
+    scope?: {
+        light: string;
+        dark: string;
+    };
+    /** Roles to emit when target is 'preview'. Defaults to all roles. */
+    roles?: AXThemeBuilderColors[];
+}
+interface AXTheme {
+    /** The generated CSS. */
+    css: string;
+    /** Generated shade scales per role, for both modes. */
+    palette: AXThemeBuilderFullPalette;
+}
+/**
+ * Creates an ACoreX theme from a flat map of role seed colors.
+ *
+ * Each provided color is applied to both light and dark modes; dark shades are
+ * derived via the dark-palette tone mapping. Omitted roles fall back to the
+ * packaged default seeds (which may differ per mode for `secondary`, `danger`, and `surface`).
+ */
+declare function createTheme(colors?: AXThemeColors, options?: AXCreateThemeOptions): AXTheme;
+
+export { createTheme };
+export type { AXCreateThemeOptions, AXTheme, AXThemeBuilderBaseColors, AXThemeBuilderColorVariants, AXThemeBuilderColors, AXThemeBuilderFullPalette, AXThemeBuilderPalette, AXThemeColors };

package/types/acorex-core-utils.d.ts

@@ -83,33 +83,71 @@ declare function debounceAsync<T extends (...args: any[]) => Promise<any>>(fn: T
  */
 declare function fallbackChain<T>(tasks: Array<() => Promise<T>>): Promise<T>;
 
+type AXHighlightTarget = string | Element | readonly Element[];
+interface AXHighlightOptions {
+    /** When false (default), matching is case-insensitive. */
+    caseSensitive?: boolean;
+    /** When true, only match whole words. */
+    wholeWord?: boolean;
+    /** Maximum number of matches to highlight across all targets. */
+    maxMatches?: number;
+    /** CSS class applied to highlighted match spans. */
+    highlightClass?: string;
+    /** CSS class applied to the wrapper span around highlighted text nodes. */
+    wrapperClass?: string;
+    /** Parent tag names whose text content is skipped. */
+    ignoredTags?: readonly string[];
+}
 /**
  * Service for applying and resetting text highlighting within specified HTML elements.
  */
 declare class AXHighlightService {
-    private querySelector;
-    private searchValue;
+    private readonly document;
+    private readonly platformId;
+    private readonly selectorStates;
+    private readonly elementStates;
+    private readonly trackedElements;
     /**
-     * Highlights all occurrences of a search value within the elements matching the provided query selector.
+     * Highlights all occurrences of a search value within the elements matching the provided target.
      *
-     * @param querySelector - CSS selector to identify target elements.
-     * @param searchValue - Text to search and highlight.
+     * @param target - CSS selector, a single element, or an array of elements to search within.
+     * @param term - Text or list of texts to search and highlight.
+     * @param options - Optional highlight behavior configuration.
+     * @returns The number of matches highlighted.
      */
-    highlight(querySelector: string, searchValue: string): void;
+    highlight(target: AXHighlightTarget, term: string | readonly string[], options?: AXHighlightOptions): number;
     /**
-     * Resets highlighted text within the elements matching the query selector.
+     * Resets highlighted text within the elements matching the target.
+     * When no target is provided, clears all highlights registered by this service.
      *
-     * @param querySelector - CSS selector to clear. Falls back to the last selector used by `highlight`.
+     * @param target - CSS selector, element, or elements to clear.
      */
-    clear(querySelector?: string): void;
+    clear(target?: AXHighlightTarget): void;
+    private toElementArray;
+    private normalizeTerms;
+    private resolveOptions;
+    private registerState;
+    private resolveRoots;
     private createSearchRegex;
-    private applyHighlight;
-    private recursivelyHighlight;
-    private createHighlightedHTML;
+    private collectTextNodes;
+    private highlightTextNode;
+    private clearSelector;
+    private clearElement;
+    private unwrapHighlight;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXHighlightService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<AXHighlightService>;
 }
 
+interface AXHighlightSegment {
+    text: string;
+    match: boolean;
+}
+/**
+ * Splits text into highlighted and non-highlighted segments for template rendering.
+ * Uses the same matching semantics as {@link AXHighlightService}.
+ */
+declare function splitHighlightSegments(text: string, term: string | readonly string[], options?: AXHighlightOptions): AXHighlightSegment[];
+
 /** ACoreX layout size classes applied on a host or container. */
 declare const AX_SIZE_CLASSES: readonly ["ax-xs", "ax-sm", "ax-md", "ax-lg", "ax-xl"];
 type AXSizeClass = (typeof AX_SIZE_CLASSES)[number];
@@ -149,5 +187,5 @@ declare function getWordBoundsAtPosition(str: string, position: number): {
     end: number;
 };
 
-export { AXAutoUnsubscriber, AXColorUtil, AXDrawingUtil, AXHighlightService, AXHtmlUtil, AXUnsubscriber, AX_SIZE_CLASSES, debounceAsync, delay, fallbackChain, getWordBoundsAtPosition, pollUntil, pollUntilAbortable, retryUntil, throttleAsync, waitFor };
-export type { AXBoundingClientRect, AXClosestAxSizeMatch, AXColorFormat, AXColorMode, AXPoint, AXSizeClass };
+export { AXAutoUnsubscriber, AXColorUtil, AXDrawingUtil, AXHighlightService, AXHtmlUtil, AXUnsubscriber, AX_SIZE_CLASSES, debounceAsync, delay, fallbackChain, getWordBoundsAtPosition, pollUntil, pollUntilAbortable, retryUntil, splitHighlightSegments, throttleAsync, waitFor };
+export type { AXBoundingClientRect, AXClosestAxSizeMatch, AXColorFormat, AXColorMode, AXHighlightOptions, AXHighlightSegment, AXHighlightTarget, AXPoint, AXSizeClass };