@scion/components 22.1.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,35 +1,6 @@
 import * as _angular_core from '@angular/core';
 import { Signal, ElementRef } from '@angular/core';
 
-/**
- * Provides the native scrollbar tracksize.
- */
-declare class SciNativeScrollbarTrackSizeProvider {
-    private readonly _document;
-    private readonly _zone;
-    /**
-     * Provides the track size of the native scrollbar, or `null` if the native scrollbars sit on top of the content.
-     */
-    trackSize: Signal<NativeScrollbarTrackSize | null>;
-    constructor();
-    /**
-     * Computes the native scrollbar track size.
-     *
-     * @returns native track size, or `null` if the native scrollbars sit on top of the content.
-     */
-    private computeTrackSize;
-    private createNativeScrollbarTrackSizeSignal;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciNativeScrollbarTrackSizeProvider, never>;
-    static ɵprov: _angular_core.ɵɵInjectableDeclaration<SciNativeScrollbarTrackSizeProvider>;
-}
-/**
- * Represents the native scrollbar track size.
- */
-interface NativeScrollbarTrackSize {
-    hScrollbarTrackHeight: number;
-    vScrollbarTrackWidth: number;
-}
-
 /**
  * Represents a viewport with slotted content (`<ng-content>`) used as scrollable content. By default, content is added to a CSS grid layout.
  *
@@ -109,8 +80,10 @@ declare class SciViewportComponent {
     private readonly _host;
     private readonly _viewport;
     private readonly _viewportClient;
-    protected readonly nativeScrollbarTrackSizeProvider: SciNativeScrollbarTrackSizeProvider;
-    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.
@@ -179,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>;
 }
@@ -256,13 +229,13 @@ declare class SciScrollbarComponent {
     /**
      * Moves the scrollbar thumb to the specified position, scrolling the viewport accordingly.
      *
-     * The thumb position must be given in page coordinates relative to the top-left corner of the document.
+     * The thumb position must be given in client coordinates (relative to the top-left corner of the page viewport).
      */
     private scrollViewport;
     /**
-     * Returns the position of this component in page coordinates.
+     * Returns the position of this component in client coordinates.
      *
-     * Returned coordinates are relative to the top-left corner of the document.
+     * Returned coordinates are relative to the top-left corner of the page viewport.
      * Depending on the scrollbar orientation, returned coordinates are `[top, bottom]` or `[left, right]`.
      */
     private scrollbarComponentPosition;
@@ -293,9 +266,9 @@ declare class SciScrollbarComponent {
      */
     private thumbSize;
     /**
-     * Returns the current thumb position in page coordinates.
+     * Returns the current thumb position in client coordinates.
      *
-     * Returned coordinates are relative to the top-left corner of the document.
+     * Returned coordinates are relative to the top-left corner of the page viewport.
      * Depending on the scrollbar orientation, returned coordinates are `[top, bottom]` or `[left, right]`.
      */
     private thumbPosition;
@@ -319,16 +292,36 @@ declare class SciScrollbarComponent {
  * This directive expects its host element to be the only child in document flow in its parent DOM element. It makes the host element
  * fill up the entire space (width and height set to 100%). The parent element must have its CSS `overflow` property set to `hidden`
  * to hide the pushed out native scrollbars.
+ *
+ * This directive provides the `isNativeScrollbarCropped` signal, which indicates whether native scrollbars are pushed out of the viewport element.
+ * In templates, access it via the exported template reference variable `sciScrollable`.
+ *
+ * ```html
+ * <div sciScrollable #sciScrollable="sciScrollable" #viewport>
+ *   content
+ * </div>
+ *
+ * <!-- Render scrollbars only if native scrollbars are pushed out of the viewport element. -->
+ * @if (sciScrollable.isNativeScrollbarCropped()) {
+ *   <sci-scrollbar [viewport]="viewport" direction="vscroll"/>
+ *   <sci-scrollbar [viewport]="viewport" direction="hscroll"/>
+ * }
+ * ```
  */
 declare class SciScrollableDirective {
     /**
      * Controls whether to display native scrollbars.
+     *
      * Has no effect if the native scrollbar sits on top of the content, e.g. in OS X.
      */
     readonly displayNativeScrollbar: _angular_core.InputSignal<boolean>;
     private readonly _host;
     private readonly _renderer;
     private readonly _nativeScrollbarTrackSizeProvider;
+    /**
+     * Indicates whether native scrollbars are pushed out of the viewport element.
+     */
+    readonly isNativeScrollbarCropped: _angular_core.Signal<boolean>;
     constructor();
     /**
      * Controls the display of the native scrollbar based on this directive's configuration.
@@ -344,7 +337,7 @@ declare class SciScrollableDirective {
     private shiftNativeScrollbars;
     private setStyle;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciScrollableDirective, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SciScrollableDirective, "[sciScrollable]", never, { "displayNativeScrollbar": { "alias": "sciScrollableDisplayNativeScrollbar"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SciScrollableDirective, "[sciScrollable]", ["sciScrollable"], { "displayNativeScrollbar": { "alias": "sciScrollableDisplayNativeScrollbar"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { SciScrollableDirective, SciScrollbarComponent, SciViewportComponent };

package/viewport/scrollbar/_scrollbar.scss

@@ -9,15 +9,15 @@
   position: absolute;
 
   &.vertical {
-    top: 1px;
+    top: 2px;
     right: 1px;
-    bottom: 1px;
+    bottom: 2px;
   }
 
   &.horizontal {
-    left: 1px;
+    left: 2px;
     bottom: 1px;
-    right: 1px;
+    right: 2px;
   }
 }
 

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,
-);