@scion/components 22.2.0 → 22.3.0

package/table/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../fesm2022/scion-components-table.mjs",
+  "typings": "../types/scion-components-table.d.ts"
+}

package/text/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../fesm2022/scion-components-text.mjs",
+  "typings": "../types/scion-components-text.d.ts"
+}

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

@@ -0,0 +1,185 @@
+import * as i0 from '@angular/core';
+import { Signal, Injector, Provider, DestroyableInjector, Binding, Type, TemplateRef } from '@angular/core';
+import { Observable } from 'rxjs';
+import { ComponentType } from '@angular/cdk/portal';
+
+/**
+ * Represents a value or a {@link Signal} of that value.
+ */
+type MaybeSignal<T> = T | Signal<T>;
+/**
+ * Coerces the given value into a {@link Signal}. If the value is already a signal, it is returned as-is; otherwise, it is wrapped in a signal.
+ *
+ * Passing `undefined` returns `undefined`, unless the option `coerceUndefined` is set to `true`.
+ *
+ * @param value - Specifies the value to coerece.
+ */
+declare function coerceSignal<T extends MaybeSignal<unknown>>(value: T): T extends Signal<unknown> ? T : T extends undefined ? undefined : Signal<T>;
+/**
+ * Coerces the given value into a {@link Signal}. If the value is already a signal, it is returned as-is; otherwise, it is wrapped in a signal.
+ *
+ * @param value - Specifies the value to coerece.
+ * @param options - Controls coercion.
+ * @param options.coerceUndefined - If `true`, returns `signal(undefined)` for a `undefined` value. Defaults to `false`.
+ */
+declare function coerceSignal<T>(value: MaybeSignal<T> | undefined, options: {
+    coerceUndefined: true;
+}): Signal<T | undefined>;
+/**
+ * Like {@link toObservable}, but lazily creates the effect upon subscription, binding it to the subscription lifecycle instead of the injection context, plus, emits the signal's initial value synchronously.
+ */
+declare function toLazyObservable<T>(signal: MaybeSignal<NonNullable<T>>, options?: {
+    injector?: Injector;
+}): Observable<NonNullable<T>>;
+declare function toLazyObservable<T>(signal: MaybeSignal<NonNullable<T>> | undefined, options?: {
+    injector?: Injector;
+}): Observable<NonNullable<T>> | undefined;
+
+/**
+ * Creates a {@link DestroyableInjector} bound to the lifecycle of its parent injector. Defaults to the current injector if not configuring a parent injector.
+ *
+ * Unlike injectors created via {@link Injector.create}, the returned injector:
+ * - Is destroyed with its parent, also if used outside a component injection context.
+ * - Does not throw an error when invoking {@link DestroyableInjector.destroy} if already destroyed.
+ * - Uses the current injection context as parent if no explicit parent injector is specified.
+ *
+ * @docs-private Not public API. For internal use only.
+ *
+ * @param options - Configures the injector.
+ * @param options.parent - Specifies the parent injector. Defaults to the current injector.
+ * @param options.providers - Specifies providers to associate with the injector.
+ * @param options.name - Names the injector, useful for debugging the injector hierarchy.
+ */
+declare function createDestroyableInjector(options?: {
+    parent?: Injector;
+    providers?: Provider[];
+    name?: string;
+}): DestroyableInjector;
+/**
+ * Asserts that the current stack frame is within an injection context and has access to inject.
+ *
+ * Delegates to `assertInInjectionContext` from @angular/core, adding the given message to the error if the assertion fails.
+ *
+ * @docs-private Not public API. For internal use only.
+ */
+declare function assertInInjectionContext(debugFn: Function, message: string): void;
+
+/**
+ * Renders a component based on a descriptor, similar to `ngComponentOutlet`, but with input bindings.
+ *
+ * Usage:
+ *
+ * ```html
+ * <ng-container *sciComponentOutlet="descriptor"/>
+ * ````
+ *
+ * ```ts
+ * protected readonly descriptor: SciComponentDescriptor = {
+ *   component: FilterComponent,
+ *   bindings: [
+ *     inputBinding('placeholder', signal('Filter items...')),
+ *   ],
+ * };
+ * ```
+ */
+declare class SciComponentOutletDirective {
+    /**
+     * Specifies the component to render.
+     */
+    readonly descriptor: i0.InputSignal<SciComponentDescriptor | null | undefined>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<SciComponentOutletDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SciComponentOutletDirective, "ng-template[sciComponentOutlet]", never, { "descriptor": { "alias": "sciComponentOutlet"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * Describes the rendering of a component.
+ */
+interface SciComponentDescriptor {
+    /**
+     * Specifies the component to render.
+     */
+    component: ComponentType<unknown>;
+    /**
+     * Specifies input and output bindings.
+     *
+     * @example - Passing inputs to the component
+     * ```ts
+     * bindings: [inputBinding('placeholder', signal('Filter items...'))];
+     * ```
+     *
+     * Inputs are available as input properties in the component.
+     *
+     * @example - Reading inputs in the component
+     * ```ts
+     * public placeholder = input.required<string>();
+     * ```
+     *
+     * @see inputBinding
+     * @see outputBinding
+     * @see twoWayBinding
+     */
+    bindings?: Binding[];
+    /**
+     * Specifies directives to be applied to the component.
+     */
+    directives?: Array<Type<unknown> | {
+        type: Type<unknown>;
+        bindings: Binding[];
+    }>;
+    /**
+     * Specifies the injector used to instantiate the component, giving control over which objects are available for injection. Defaults to the element injector.
+     *
+     * ```ts
+     * Injector.create({
+     *   parent: ...,
+     *   providers: [
+     *    {provide: <TOKEN>, useValue: <VALUE>}
+     *   ],
+     * })
+     * ```
+     */
+    injector?: Injector;
+    /**
+     * Specifies providers available for injection in the component.
+     */
+    providers?: Provider[];
+    /**
+     * Specifies CSS classes to associate with the component.
+     */
+    cssClass?: MaybeSignal<string | string[]>;
+    /**
+     * Specifies HTML attributes to associate with the component.
+     *
+     * Data attributes should start with the `data-` prefix.
+     */
+    attributes?: MaybeSignal<{
+        [name: string]: string | undefined;
+    }>;
+}
+
+/**
+ * Use to add specified attributes to the host element.
+ */
+declare class SciAttributesDirective {
+    /**
+     * Specifies attributes to add to the host element.
+     *
+     * Attributes with `null` or `undefined` values are removed.
+     */
+    readonly attributes: i0.InputSignal<{
+        [name: string]: unknown;
+    } | null | undefined>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<SciAttributesDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SciAttributesDirective, "[sciAttributes]", never, { "attributes": { "alias": "sciAttributes"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+interface SciTemplateDescriptor {
+    template: MaybeSignal<TemplateRef<unknown>>;
+    context?: {
+        [key: string]: MaybeSignal<unknown>;
+    };
+}
+
+export { SciAttributesDirective, SciComponentOutletDirective, assertInInjectionContext, coerceSignal, createDestroyableInjector, toLazyObservable };
+export type { MaybeSignal, SciComponentDescriptor, SciTemplateDescriptor };

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

@@ -0,0 +1,146 @@
+import * as i0 from '@angular/core';
+import { Signal, EnvironmentProviders } from '@angular/core';
+import { SciComponentDescriptor } from '@scion/components/common';
+import { ComponentType } from '@angular/cdk/portal';
+
+/**
+ * Renders an icon based on registered icon providers.
+ *
+ * Set the icon name as the slotted content of the `<sci-icon>` component.
+ *
+ * Example:
+ * ```html
+ * <sci-icon>home</sci-icon>
+ * ```
+ *
+ * An icon provider can be registered using {@link provideIconProvider}.
+ *
+ * Providers are called in registration order. If a provider does not provide the icon, the next provider is called, and so on.
+ * If no provider provides the icon, defaults to a Material icon provider, interpreting the icon as a Material icon font ligature.
+ * Refer to https://fonts.google.com/icons for available Material icons and instructions on including the Material icon font.
+ *
+ * By default, the icon size is `1em`. To change the size, set the font-size on the `<sci-icon>` element or use the `--sci-icon-size` CSS variable.
+ *
+ * ```scss
+ * sci-icon {
+ *   --sci-icon-size: 16px;
+ * }
+ * ```
+ *
+ * @see provideIconProvider
+ *
+ * TODO [Angular 23] Consider changing encapsulation to `IsolatedShadowDom` when stable. See branch: issue/icon-shadow-dom.
+ */
+declare class SciIconComponent {
+    private readonly _slottedContent;
+    protected readonly icon: Signal<SciComponentDescriptor | undefined>;
+    /**
+     * Reads the icon from slotted content and passes it to registered icon providers for resolution.
+     */
+    private computeIcon;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SciIconComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SciIconComponent, "sci-icon", never, {}, {}, never, ["*"], true, never>;
+}
+
+/**
+ * Enables contribution or replacement of icons used in SCION.
+ *
+ * An icon provider is a function that returns a component for an icon. The component renders the icon.
+ *
+ * Multiple icon providers can be registered. Providers are called in registration order. If a provider does not provide the icon,
+ * the next provider is called, and so on.
+ *
+ * Defaults to a Material icon provider, interpreting the icon as a Material icon ligature.
+ *
+ * Refer to https://fonts.google.com/icons for available Material icons and https://developers.google.com/fonts/docs/material_symbols#use_in_web
+ * for instructions on including the Material icon font.
+ *
+ * @example - Importing the Material icon font in `styles.scss`
+ * ```scss
+ * @import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL@20..24,400,0&display=block');
+ * ```
+ *
+ * SCION uses the following built-in icons:
+ * - scion.add               : Add an item
+ * - scion.add_large         : Add an item (large)
+ * - scion.bin               : Bin symbol
+ * - scion.checkmark         : Indicates a selected option
+ * - scion.chevron_down      : Chevron down symbol
+ * - scion.chevron_left      : Chevron left symbol
+ * - scion.chevron_right     : Chevron right symbol
+ * - scion.chevron_up        : Chevron up symbol
+ * - scion.clear             : Clear items
+ * - scion.close             : Close a popover
+ * - scion.collapse_all      : Collapse all items
+ * - scion.copy              : Copy an item
+ * - scion.delete            : Delete an item
+ * - scion.dirty             : Indicates unsaved data
+ * - scion.drag_handle       : Drag or move an item
+ * - scion.duplicate         : Duplicate an item
+ * - scion.edit              : Edit an item
+ * - scion.emdash            : Em dash symbol
+ * - scion.envelope          : Envelope symbol
+ * - scion.envelope_closed   : Indicates a closed envelope
+ * - scion.envelope_opened   : Indicates an opened envelope
+ * - scion.expand_all        : Expand an item
+ * - scion.external_link     : Open link in a new tab
+ * - scion.filter            : Set or change a filter
+ * - scion.find              : Find an item
+ * - scion.folder            : Directory symbol
+ * - scion.help              : Indicates help, support, or documentation
+ * - scion.hide              : Hide a panel
+ * - scion.magnifier         : Magnifier symbol
+ * - scion.minimize          : Minimize a panel
+ * - scion.minus             : Minus sign
+ * - scion.modified          : Indicates modified data
+ * - scion.more_horizontal   : Show a popover to the left or right
+ * - scion.more_vertical     : Show a popover above or below
+ * - scion.new               : Create an item
+ * - scion.new_large         : Create an item (large)
+ * - scion.paste             : Paste from clipboard
+ * - scion.pen               : Pen symbol
+ * - scion.pin               : Pin an item
+ * - scion.pinned            : Indicates a pinned item
+ * - scion.placeholder_frame : Placeholder symbol
+ * - scion.placeholder_image : Placeholder symbol for an image
+ * - scion.plus              : Plus sign
+ * - scion.plus_large        : Plus sign (large)
+ * - scion.remove            : Remove an item (x)
+ * - scion.remove_minus      : Remove an item (-)
+ * - scion.reset             : Reset a form
+ * - scion.search            : Search for an item
+ * - scion.sort_ascending    : Sort items in ascending order (A-Z, 0-9)
+ * - scion.sort_by           : Change sort order
+ * - scion.sort_descending   : Sort items in descending order (Z-A, 9-0)
+ * - scion.user              : User symbol
+ *
+ * To not replace built-in icons, the icon provider can return `undefined` for icons starting with the `scion.` prefix.
+ *
+ * The function can call `inject` to get any required dependencies.
+ *
+ * @see SciIconProviderFn
+ * @see SciIconComponent
+ */
+declare function provideIconProvider(iconProviderFn: SciIconProviderFn | undefined): EnvironmentProviders;
+/**
+ * Signature of a function to provide icons.
+ *
+ * An icon provider is a function that returns the component for an icon. The component renders the icon.
+ *
+ * Alternatively, the icon provider can return a descriptor, allowing for additional configuration such as inputs.
+ * Inputs are available as input properties in the component. The component can use the inputs to render the icon.
+ *
+ * Icon keys used by SCION start with the `scion.` prefix. To not replace built-in icons, the icon provider can
+ * return `undefined` for icons starting with the `scion.` prefix.
+ *
+ * An icon provider can be registered via {@link provideIconProvider} function.
+ *
+ * The function can call `inject` to get any required dependencies.
+ *
+ * @param icon - The key of the icon for which to provide the icon component.
+ * @returns ComponentType or {@link SciComponentDescriptor} to render the icon, or `undefined` if not provided by the icon provider.
+ */
+type SciIconProviderFn = (icon: string) => ComponentType<unknown> | SciComponentDescriptor | undefined;
+
+export { SciIconComponent, provideIconProvider };
+export type { SciIconProviderFn };