@star-ng/ui 0.0.0-stage → 0.2.0

package/types/star-ng-ui-core.d.ts

@@ -0,0 +1,373 @@
+import * as i0 from "@angular/core";
+import { EffectRef, EnvironmentProviders, InjectionToken, Injector, Provider } from "@angular/core";
+import { FormArray, FormGroup } from "@angular/forms";
+/** Text direction of an element: left-to-right or right-to-left. */
+export type StarDirection = 'ltr' | 'rtl';
+/**
+ * Text direction in force at one element. A `dir` attribute on the element or on an ancestor
+ * decides; with `dir="auto"` or no attribute the computed `direction` decides. The function
+ * reads the DOM each time it is called, so a handler that calls it follows a direction change at
+ * run time, and a part of the page that has its own `dir` attribute is respected.
+ *
+ * Controls use it in key handlers and pointer math: the horizontal arrow keys follow the visual
+ * direction, so in `rtl` the left arrow means "next".
+ */
+export declare function starDirectionOf(element: Element | null | undefined): StarDirection;
+/** `true` when the element is laid out right-to-left. See `starDirectionOf`. */
+export declare function starIsRtl(element: Element | null | undefined): boolean;
+/**
+ * Key of a keyboard event in "inline" terms: `'ArrowRight'` means toward the end of the line and
+ * `'ArrowLeft'` toward the start, whatever the direction. In right-to-left the two arrow keys are
+ * swapped; every other key is returned as it is. A handler can then be written once, as for
+ * left-to-right text:
+ *
+ * ```ts
+ * switch (starInlineKey(event)) {
+ *   case 'ArrowRight': // next item in reading order
+ * }
+ * ```
+ *
+ * The element decides the direction; it defaults to `event.currentTarget`.
+ */
+export declare function starInlineKey(event: KeyboardEvent, element?: Element | null): string;
+/**
+ * Direction of the application: the `dir` attribute of `<html>` (or `<body>`), followed at run
+ * time. Controls that open an overlay or a menu (CDK `Overlay`, `CdkMenu`) inject it. It does
+ * two things:
+ *
+ * 1. `value` is a signal, so a control can react when the application switches the direction.
+ * 2. It keeps the root `Directionality` of `@angular/cdk/bidi` in step with the page. That
+ *    service reads the attribute once when it is created; without this, overlays and menus
+ *    would keep the old direction after a switch.
+ *
+ * The application only sets `dir` on `<html>`: `document.documentElement.dir = 'rtl'`.
+ */
+export declare class StarDirectionService {
+  private readonly document;
+  private readonly directionality;
+  private readonly current;
+  /** The direction of the page now. */
+  readonly value: import("@angular/core").Signal<StarDirection>;
+  constructor();
+  /** Reads the attribute again. The observer calls it; call it by hand after a change that the observer cannot see. */
+  refresh(): void;
+  private read;
+  private sync;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarDirectionService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * Starts `StarDirectionService` when the application starts. Optional: the controls that open
+ * an overlay start the service themselves. Use it when the direction changes at run time before
+ * any such control exists, or when your own code reads `StarDirectionService.value`.
+ *
+ * ```ts
+ * bootstrapApplication(App, { providers: [provideStarDirection()] });
+ * ```
+ */
+export declare function provideStarDirection(): EnvironmentProviders;
+/**
+ * Pure helpers of the windowed option lists: row model, index math, keyboard target and ARIA
+ * values. `star-listbox` and the select family (`star-select`, `star-multi-select`,
+ * `star-autocomplete`) use them. They have no DOM access, so unit tests can check them without
+ * layout. They are exported because entry points import each other by package name. They are
+ * helpers of the library, not a stable extension point.
+ */
+/** One row of a windowed list. Group headings and options have the same height. */
+export type StarWindowRow<T> = {
+  readonly kind: 'group';
+  readonly key: string;
+  readonly label: string;
+  readonly id: string;
+} | {
+  readonly kind: 'option';
+  readonly key: string;
+  readonly option: T;
+  /** Index in the visible options (keyboard order). */
+  readonly index: number;
+  /** Id of the heading row of the group, or null without groups. */
+  readonly groupId: string | null;
+  /** Index of the heading row of the group, or -1 without groups. */
+  readonly groupRow: number;
+};
+/** The rows, and for each visible option the index of its row. */
+export interface StarWindowLayout<T> {
+  readonly rows: readonly StarWindowRow<T>[];
+  readonly rowOfOption: readonly number[];
+}
+/**
+ * Flattens headings and options into one list of rows of equal height. `options` must already be
+ * in display order (each group together). A heading comes before the first option of each group.
+ * The heading id has the form `<idPrefix>-group-<index of the first option of the group>`.
+ */
+export declare function starListLayout<T>(options: readonly T[], groupOf: ((option: T) => string) | null, idPrefix: string): StarWindowLayout<T>;
+/** Number of options a Page up / Page down key moves: the lines in view, minus one for overlap. */
+export declare function starListPageSize(viewportHeight: number, itemSize: number): number;
+export type StarListNavigationKey = 'ArrowDown' | 'ArrowUp' | 'Home' | 'End' | 'PageDown' | 'PageUp';
+/** Index of the option a navigation key moves to, limited to the list. -1 for an empty list. */
+export declare function starListKeyboardTarget(key: StarListNavigationKey, active: number, count: number, page: number): number;
+/** Index of the first option whose label starts with the typed text (compared in lower case). */
+export declare function starListTypeaheadIndex(count: number, labelAt: (index: number) => string, typed: string): number;
+/** First and last row to bring into view for an option: its heading row comes with the first option. */
+export declare function starListRevealRows<T>(layout: StarWindowLayout<T>, index: number): [number, number];
+/**
+ * Scroll offset that brings rows `first` to `last` into view with the least movement, or null when
+ * they are in view. Rows have the height `itemSize`. `inset` is the space above the first row
+ * (the padding of the scroll container): a row below the view is moved by it, and the first row
+ * scrolls to the very top so that the padding shows.
+ */
+export declare function starListRevealOffset(first: number, last: number, itemSize: number, scrollOffset: number, viewportHeight: number, inset?: number): number | null;
+/** `aria-setsize` and `aria-posinset` of an option, for the whole list. */
+export declare function starListAriaPosition(index: number, count: number): {
+  setsize: number;
+  posinset: number;
+};
+/** CSS height of the list: `scrollHeight` at most, and no taller than the rows need. */
+export declare function starListHeight(scrollHeight: string, rowCount: number, itemSize: number): string;
+/** True when a row is inside the rendered range `[start, end)`. */
+export declare function starListRowRendered(row: number, range: {
+  start: number;
+  end: number;
+}): boolean;
+/**
+ * How a list control reads a property from an option: a property name or an accessor function.
+ * Same idea as PrimeNG `optionLabel` / `optionValue` / `optionDisabled`, but type safe.
+ */
+export type StarOptionKey<T, R = unknown> = (keyof T & string) | ((option: T) => R);
+export type StarSeverity = 'primary' | 'secondary' | 'success' | 'info' | 'warn' | 'danger';
+export type StarSize = 'sm' | 'md' | 'lg';
+export declare function readOption<T, R>(option: T, key: StarOptionKey<T, R> | null | undefined): unknown;
+/** Text shown for an option. Falls back to the option itself for primitive options. */
+export declare function optionText<T>(option: T, key: StarOptionKey<T> | null | undefined): string;
+/** Locale-aware compare used by sorting: numbers and dates numerically, text with Intl.Collator. */
+export declare function compareValues(a: unknown, b: unknown): number;
+/** Case- and accent-insensitive "contains" match used by filters. */
+export declare function matchesFilter(text: string, query: string): boolean;
+/**
+ * Keeps a Reactive `FormGroup` (or `FormArray`) in step with the `SignalFormControl`s inside it.
+ *
+ * Angular 22 updates a parent group when a `SignalFormControl` value changes, but not when a
+ * Signal Forms rule (for example `disabled({ when })` or a conditional `required`) changes the
+ * child's status without a value change. The group then reports a stale `valid` / `status`.
+ * This effect watches every signal control's validity, disabled and pending state and calls
+ * `updateValueAndValidity()` on the group when one changes.
+ *
+ * Call it in an injection context (a field initializer or constructor):
+ * ```ts
+ * readonly form = new FormGroup({ country: new SignalFormControl<string | null>(null, rules) });
+ * private readonly sync = syncSignalFormControls(this.form);
+ * ```
+ */
+export declare function syncSignalFormControls(group: FormGroup | FormArray, injector?: Injector): EffectRef;
+/**
+ * Built-in texts of the StarNG UI controls (screen-reader labels, empty states, reports).
+ * Defaults are English. Override them once at app level:
+ * - `provideStarUiTextFromTransloco()` reads them from the active Transloco language (`ui.*` keys)
+ *   and updates the controls live when the language changes.
+ * - `provideStarUiText({...})` sets fixed texts.
+ *
+ * Function entries take values (for example a count) and return the full sentence, so word order
+ * can change per language. Their parameter names are listed in `STAR_UI_TEXT_PARAMS`.
+ */
+export interface StarUiText {
+  readonly close: string;
+  readonly clear: string;
+  readonly loading: string;
+  readonly actions: string;
+  readonly moreActions: string;
+  readonly ofTotal: (index: number, total: number) => string;
+  readonly expandItem: (label: string) => string;
+  readonly collapseItem: (label: string) => string;
+  readonly removeItem: (label: string) => string;
+  readonly tagsHint: string;
+  readonly tagAdded: (label: string) => string;
+  readonly tagRemoved: (label: string) => string;
+  readonly tagInvalid: (label: string) => string;
+  readonly tagDuplicate: (label: string) => string;
+  readonly tagLimit: (max: number) => string;
+  readonly notifications: string;
+  readonly accept: string;
+  readonly reject: string;
+  readonly selectPlaceholder: string;
+  readonly filterPlaceholder: string;
+  readonly emptyMessage: string;
+  readonly emptyFilterMessage: string;
+  readonly selectAll: string;
+  readonly selectedItems: (count: number) => string;
+  readonly searching: string;
+  readonly showOptions: string;
+  readonly resultsAvailable: (count: number) => string;
+  readonly pagination: string;
+  readonly firstPage: string;
+  readonly previousPage: string;
+  readonly nextPage: string;
+  readonly lastPage: string;
+  readonly page: (page: number) => string;
+  readonly rowsPerPage: string;
+  readonly pageReport: (first: number, last: number, total: number) => string;
+  readonly noData: string;
+  readonly selectRow: string;
+  readonly selectAllRows: string;
+  readonly filterBy: (column: string) => string;
+  readonly filterAll: string;
+  readonly filterMin: (column: string) => string;
+  readonly filterMax: (column: string) => string;
+  readonly filterMinShort: string;
+  readonly filterMaxShort: string;
+  readonly expandRow: string;
+  readonly collapseRow: string;
+  readonly rowDetails: string;
+  readonly reorderRows: string;
+  readonly sortMultiHint: string;
+  readonly terminalCommand: string;
+  readonly compareImages: string;
+  readonly editCell: (column: string) => string;
+  readonly columns: string;
+  readonly resizeColumn: (column: string) => string;
+  readonly moveColumnEarlier: (column: string) => string;
+  readonly moveColumnLater: (column: string) => string;
+  readonly layout: string;
+  readonly layoutList: string;
+  readonly layoutGrid: string;
+  readonly moveSelectedItem: string;
+  readonly orderListHint: string;
+  readonly moveTop: string;
+  readonly moveUp: string;
+  readonly moveDown: string;
+  readonly moveBottom: string;
+  readonly itemPosition: (label: string, position: number, total: number) => string;
+  readonly transfer: string;
+  readonly moveSelectedToTarget: string;
+  readonly moveAllToTarget: string;
+  readonly moveSelectedToSource: string;
+  readonly moveAllToSource: string;
+  readonly pickListSource: string;
+  readonly pickListTarget: string;
+  readonly chooseDate: string;
+  readonly chooseMonth: string;
+  readonly chooseYear: string;
+  readonly previousMonth: string;
+  readonly nextMonth: string;
+  readonly previousYears: string;
+  readonly nextYears: string;
+  readonly today: string;
+  readonly time: string;
+  readonly startTime: string;
+  readonly weekNumber: string;
+  readonly weekShort: string;
+  readonly endTime: string;
+  readonly done: string;
+  readonly increase: string;
+  readonly decrease: string;
+  readonly showPassword: string;
+  readonly hidePassword: string;
+  readonly passwordWeak: string;
+  readonly passwordFair: string;
+  readonly passwordGood: string;
+  readonly passwordStrong: string;
+  readonly passwordRuleLength: (min: number) => string;
+  readonly passwordRuleUpper: string;
+  readonly passwordRuleLower: string;
+  readonly passwordRuleNumber: string;
+  readonly passwordRuleSymbol: string;
+  readonly ruleMet: string;
+  readonly ruleNotMet: string;
+  readonly otpLabel: string;
+  readonly otpCharacter: (position: number, total: number) => string;
+  readonly ratingLabel: string;
+  readonly sliderMinimum: (label: string) => string;
+  readonly sliderMaximum: (label: string) => string;
+  readonly colorLabel: string;
+  readonly customColor: string;
+  readonly hexValue: (label: string) => string;
+  readonly chooseFiles: string;
+  readonly dropFiles: string;
+  readonly fileMaxSize: (size: string) => string;
+  readonly fileUpTo: (count: number) => string;
+  readonly uploadingFile: (name: string) => string;
+  readonly uploaded: string;
+  readonly fileTypeNotAllowed: (name: string) => string;
+  readonly fileTooLarge: (name: string, max: string) => string;
+  readonly fileLimitReached: (limit: number) => string;
+  readonly editorLabel: string;
+  readonly editorFormatting: (label: string) => string;
+  readonly editorBold: string;
+  readonly editorItalic: string;
+  readonly editorUnderline: string;
+  readonly editorHeading: string;
+  readonly editorBulletList: string;
+  readonly editorNumberedList: string;
+  readonly editorClearFormatting: string;
+  readonly editorLink: string;
+  readonly editorLinkPrompt: string;
+  readonly breadcrumb: string;
+  readonly stepperLabel: string;
+  readonly stepCompleted: string;
+  readonly resizePanes: string;
+  readonly dock: string;
+  readonly scrollToTop: string;
+  readonly theme: string;
+  readonly themeSystem: string;
+  readonly themeLight: string;
+  readonly themeDark: string;
+  readonly pauseSlides: string;
+  readonly playSlides: string;
+  readonly previousSlides: string;
+  readonly nextSlides: string;
+  readonly galleryLabel: string;
+  readonly previousImage: string;
+  readonly nextImage: string;
+  readonly showImage: (alt: string) => string;
+  readonly previewImage: (alt: string) => string;
+  readonly zoomIn: string;
+  readonly zoomOut: string;
+  readonly chartView: string;
+  readonly tableView: string;
+  readonly chartTotal: string;
+  readonly chartOther: string;
+  readonly chartCategory: string;
+  readonly chartValue: string;
+  readonly chartShare: string;
+  readonly chartSeries: string;
+  readonly chartX: string;
+  readonly chartY: string;
+  readonly chartTypeBar: string;
+  readonly chartTypeStackedBar: string;
+  readonly chartTypeLine: string;
+  readonly chartTypeArea: string;
+  readonly chartTypeDoughnut: string;
+  readonly chartTypePie: string;
+  readonly chartTypeRadar: string;
+  readonly chartTypePolarArea: string;
+  readonly chartTypeScatter: string;
+  readonly chartDescription: (kind: string, series: number, items: number, min: string, max: string) => string;
+  readonly meterValue: (value: string, total: number) => string;
+}
+export declare const STAR_UI_TEXT_DEFAULTS: StarUiText;
+/** Parameter names of the function entries, in call order (used for `{{ name }}` in translations). */
+export declare const STAR_UI_TEXT_PARAMS: { readonly [K in keyof StarUiText]?: readonly string[]; };
+export declare const STAR_UI_TEXT: InjectionToken<StarUiText>;
+/** Overrides some or all built-in control texts with fixed values. */
+export declare function provideStarUiText(overrides: Partial<StarUiText>): Provider;
+/**
+ * Builds a `StarUiText` whose entries read `source()` on every access. When `source` reads a
+ * signal, every OnPush control that renders a built-in text updates when that signal changes.
+ * Entries that `source()` does not return fall back to the English default.
+ *
+ * Use it in a factory when the signal lives in a service:
+ * `{ provide: STAR_UI_TEXT, useFactory: () => starUiTextFromSignal(inject(Language).text) }`.
+ */
+export declare function starUiTextFromSignal(source: () => Partial<StarUiText>): StarUiText;
+/**
+ * Provides the control texts from a function that reads a signal, so the language can change at
+ * run time without a translation library:
+ *
+ * ```ts
+ * const language = signal<'en' | 'de'>('en');
+ * provideStarUiTextFromSignal(() => (language() === 'de' ? STAR_UI_TEXT_DE : STAR_UI_TEXT_DEFAULTS));
+ * ```
+ *
+ * Do not spread a pack with getters into an object (`{ ...text }`): that reads every getter once and
+ * freezes the result. Pass a function, as shown above.
+ */
+export declare function provideStarUiTextFromSignal(source: () => Partial<StarUiText>): Provider;