@scion/components 22.2.0 → 22.3.0

package/types/scion-components-text.d.ts

@@ -0,0 +1,131 @@
+import * as i0 from '@angular/core';
+import { EnvironmentProviders, PipeTransform, Signal, Injector } from '@angular/core';
+import { MaybeSignal } from '@scion/components/common';
+
+/**
+ * Enables localization of texts used in SCION.
+ *
+ * A text provider is a function that returns the text for a translation key.
+ *
+ * Multiple text providers can be registered. Providers are called in registration order. If a provider does not provide the text,
+ * the next provider is called, and so on.
+ *
+ * The translation keys of built-in SCION texts start with the `scion.` prefix. To not localize built-in SCION texts, the text provider can return `undefined` instead.
+ *
+ * The function:
+ * - Can call `inject` to get any required dependencies.
+ * - Can use `toSignal` to convert an {@link Observable} to a {@link Signal}.
+ *
+ * @see SciTextProviderFn
+ * @see text
+ */
+declare function provideTextProvider(textProviderFn: SciTextProviderFn | undefined): EnvironmentProviders;
+/**
+ * Signature of a function to provide texts.
+ *
+ * Texts starting with the percent symbol (`%`) are passed to registered text providers for translation, with the percent symbol omitted.
+ *
+ * A text provider can be registered via {@link provideTextProvider} function.
+ *
+ * The function:
+ * - Can call `inject` to get any required dependencies.
+ * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
+ *
+ * @param key - Translation key of the text.
+ * @param params - Parameters used for text interpolation.
+ * @returns Text associated with the key, or `undefined` if not found.
+ *          Localized applications should return the text as {@link Signal} in the current language and update it on language change.
+ */
+type SciTextProviderFn = (key: string, params: {
+    [name: string]: string;
+}) => MaybeSignal<string> | undefined;
+/**
+ * Represents either a text or a key for translation.
+ *
+ * A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
+ *
+ * Key and parameters are passed to registered text providers for translation. A text provider can be registered via
+ * {@link provideTextProvider} function.
+ *
+ * Semicolons in interpolation parameters must be escaped with two backslashes (`\\;`).
+ *
+ * Examples:
+ * - `%key`: translation key
+ * - `%key;param=value`: translation key with a single interpolation parameter
+ * - `%key;param1=value1;param2=value2`: translation key with multiple interpolation parameters
+ * - `text`: no translation key; text is returned as is
+ *
+ * @see provideTextProvider
+ */
+type Translatable = string | `%${string}`;
+
+/**
+ * Gets the text for given {@link Translatable} from registered text providers.
+ *
+ * A {@link Translatable} is a string that, if it starts with the percent symbol (`%`), is passed to registered text providers for translation, with the percent symbol omitted.
+ * Otherwise, the text is returned as is.
+ *
+ * A translation key may include parameters in matrix notation for text interpolation. Escape semicolons with two backslashes (`\\;`).
+ *
+ * Examples:
+ * - `%key`: translation key
+ * - `%key;param=value`: translation key with a single interpolation parameter
+ * - `%key;param1=value1;param2=value2`: translation key with multiple interpolation parameters
+ * - `text`: no translation key; text is returned as is
+ */
+declare class SciTextPipe implements PipeTransform {
+    private _translatable;
+    private _text;
+    transform(translatable: Translatable): Signal<string>;
+    transform(translatable: Translatable | undefined): Signal<string | undefined>;
+    transform(translatable: Translatable | null): Signal<string | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SciTextPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<SciTextPipe, "sciText", true>;
+}
+
+/**
+ * Gets the text for given {@link Translatable} from registered text providers.
+ *
+ * A {@link Translatable} is a string that, if it starts with the percent symbol (`%`), is passed to registered text providers for translation, with the percent symbol omitted.
+ * Otherwise, the text is returned as is.
+ *
+ * A translation key may include parameters for text interpolation. Interpolation parameters can be passed via options or appended to the translatable in matrix notation.
+ * If appended, escape semicolons with two backslashes (`\\;`).
+ *
+ * Examples:
+ *
+ * @example - Get the text for a translation key
+ * ```ts
+ * text('%key');
+ * ```
+ *
+ * @example - Get the text for a translation key with interpolation parameters
+ * ```ts
+ * text('%key;param1=value1;param2=value2');
+ * ```
+ *
+ * @example - Alternatively, pass interpolation parameters via options
+ * ```ts
+ * text('%key', {params: {param1: 'value1', param2: 'value2'}});
+ * ```
+ *
+ * The function:
+ * - Must be called within an injection context, or an explicit {@link Injector} passed.
+ * - Must be called in a non-reactive (non-tracking) context.
+ *
+ * @param translatable - Translation key (starts with `%`) or plain text.
+ * @param options - Controls translation.
+ * @param options.injector - Injector to call text providers. Defaults to the current injection context.
+ *                           Note: Text providers may allocate resources that are released only when this injector is destroyed. Destroy the injector when the text is no longer needed.
+ * @param options.params - Parameters for text interpolation.
+ * @returns Signal with the translated text.
+ *
+ * @see provideTextProvider
+ */
+declare function text<T extends Translatable | null | undefined>(translatable: MaybeSignal<T>, options?: {
+    injector?: Injector;
+    params?: Record<string, unknown> | Map<string, unknown>;
+}): Signal<T extends null | undefined ? T : string>;
+
+export { SciTextPipe, provideTextProvider, text };
+export type { SciTextProviderFn, Translatable };

package/types/scion-components-viewport.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { ElementRef } from '@angular/core';
+import { Signal, ElementRef } from '@angular/core';
 
 /**
  * Represents a viewport with slotted content (`<ng-content>`) used as scrollable content. By default, content is added to a CSS grid layout.
@@ -80,7 +80,10 @@ declare class SciViewportComponent {
     private readonly _host;
     private readonly _viewport;
     private readonly _viewportClient;
-    constructor();
+    /**
+     * Indicates whether currently scrolling the viewport.
+     */
+    readonly scrolling: Signal<boolean>;
     focus(): void;
     /**
      * Returns the number of pixels that the viewport client is scrolled vertically.
@@ -149,9 +152,9 @@ declare class SciViewportComponent {
      */
     computeOffset(element: ElementRef<HTMLElement> | HTMLElement, border: 'left' | 'top'): number | null;
     /**
-     * Emits when the scroll position changes.
+     * Computes whether currently scrolling the viewport.
      */
-    private installScrollEmitter;
+    private computeScrolling;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciViewportComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SciViewportComponent, "sci-viewport", never, { "scrollbarStyle": { "alias": "scrollbarStyle"; "required": false; "isSignal": true; }; }, { "scroll": "scroll"; }, never, never, true, never>;
 }

package/design/components/_scion-component-tokens.scss

@@ -1,48 +0,0 @@
-@use '../theming' as sci-theming;
-
-$sci-scrollbar: (
-  --sci-scrollbar-color: var(--sci-color-gray-700),
-);
-
-$sci-viewport: (
-  --sci-viewport-scrollbar-color: var(--sci-scrollbar-color),
-);
-
-$sci-throbber: (
-  --sci-throbber-color: var(--sci-color-gray-300),
-  --sci-throbber-size: 50px,
-  --sci-throbber-duration: 1.25s,
-);
-
-$sci-splitter: (
-  --sci-splitter-background-color: var(--sci-color-border), // background color of the splitter
-  --sci-splitter-background-color-hover: var(--sci-splitter-background-color), // background color of the splitter when hovering it
-  --sci-splitter-size: 1px, // size of the splitter along the main axis (width if direction is row, or height if direction is column)
-  --sci-splitter-size-hover: 8px, // size of the splitter along the main axis when hovering it.
-  --sci-splitter-touch-target-size: 15px, // touch target size to move the splitter (accessibility)
-  --sci-splitter-cross-axis-size: 100%, // handle size along the cross axis
-  --sci-splitter-border-radius: 0, // border radius of the splitter
-  --sci-splitter-opacity-active: 1, //  opacity of the splitter while the user moves the splitter
-  --sci-splitter-opacity-hover: .3, // opacity of the splitter when hovering it
-);
-
-$sci-sashbox: (
-  --sci-sashbox-gap: 10px, // gaps (gutters) between sashes
-  --sci-sashbox-splitter-background-color: var(--sci-splitter-background-color), // background color of the splitter
-  --sci-sashbox-splitter-background-color-hover: var(--sci-splitter-background-color), // background color of the splitter when hovering it
-  --sci-sashbox-splitter-size: var(--sci-splitter-size), // size of the splitter along the main axis (width if direction is row, or height if direction is column)
-  --sci-sashbox-splitter-size-hover: var(--sci-splitter-size-hover), // size of the splitter along the main axis when hovering it.
-  --sci-sashbox-splitter-touch-target-size: var(--sci-splitter-touch-target-size), // touch target size to move the splitter (accessibility)
-  --sci-sashbox-splitter-cross-axis-size: var(--sci-splitter-cross-axis-size), // handle size along the cross axis
-  --sci-sashbox-splitter-border-radius: var(--sci-splitter-border-radius), // border radius of the splitter
-  --sci-sashbox-splitter-opacity-active: var(--sci-splitter-opacity-active), //  opacity of the splitter while the user moves the splitter
-  --sci-sashbox-splitter-opacity-hover: var(--sci-splitter-opacity-hover), // opacity of the splitter when hovering it
-);
-
-$tokens: sci-theming.map-merge(
-    $sci-scrollbar,
-    $sci-viewport,
-    $sci-throbber,
-    $sci-splitter,
-    $sci-sashbox,
-);