@ni/fast-foundation 0.0.2

package/dist/dts/data-grid/data-grid.d.ts

@@ -0,0 +1,218 @@
+import { ViewTemplate } from "@ni/fast-element";
+import { FoundationElement } from "../foundation-element/foundation-element.js";
+import type { DataGridCell } from "./data-grid-cell.js";
+import { DataGridRowTypes, GenerateHeaderOptions } from "./data-grid.options.js";
+export { DataGridRowTypes, GenerateHeaderOptions };
+/**
+ * Defines a column in the grid
+ *
+ * @public
+ */
+export interface ColumnDefinition {
+    /**
+     * Identifies the data item to be displayed in this column
+     * (i.e. how the data item is labelled in each row)
+     */
+    columnDataKey: string;
+    /**
+     * Sets the css grid-column property on the cell which controls its placement in
+     * the parent row. If left unset the cells will set this value to match the index
+     * of their column in the parent collection of ColumnDefinitions.
+     */
+    gridColumn?: string;
+    /**
+     *  Column title, if not provided columnDataKey is used as title
+     */
+    title?: string;
+    /**
+     *  Header cell template
+     */
+    headerCellTemplate?: ViewTemplate;
+    /**
+     * Whether the header cell has an internal focus queue
+     */
+    headerCellInternalFocusQueue?: boolean;
+    /**
+     * Callback function that returns the element to focus in a custom cell.
+     * When headerCellInternalFocusQueue is false this function is called when the cell is first focused
+     * to immediately move focus to a cell element, for example a cell that is a checkbox could move
+     * focus directly to the checkbox.
+     * When headerCellInternalFocusQueue is true this function is called when the user hits Enter or F2
+     */
+    headerCellFocusTargetCallback?: (cell: DataGridCell) => HTMLElement;
+    /**
+     * cell template
+     */
+    cellTemplate?: ViewTemplate;
+    /**
+     * Whether the cell has an internal focus queue
+     */
+    cellInternalFocusQueue?: boolean;
+    /**
+     * Callback function that returns the element to focus in a custom cell.
+     * When cellInternalFocusQueue is false this function is called when the cell is first focused
+     * to immediately move focus to a cell element, for example a cell that is a checkbox could move
+     * focus directly to the checkbox.
+     * When cellInternalFocusQueue is true this function is called when the user hits Enter or F2
+     */
+    cellFocusTargetCallback?: (cell: DataGridCell) => HTMLElement;
+    /**
+     * Whether this column is the row header
+     */
+    isRowHeader?: boolean;
+}
+/**
+ * A Data Grid Custom HTML Element.
+ *
+ * @slot - The default slot for custom row elements
+ * @public
+ */
+export declare class DataGrid extends FoundationElement {
+    /**
+     *  generates a basic column definition by examining sample row data
+     */
+    static generateColumns: (row: object) => ColumnDefinition[];
+    /**
+     *  generates a gridTemplateColumns based on columndata array
+     */
+    private static generateTemplateColumns;
+    /**
+     * When true the component will not add itself to the tab queue.
+     * Default is false.
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: no-tabbing
+     */
+    noTabbing: boolean;
+    private noTabbingChanged;
+    /**
+     *  Whether the grid should automatically generate a header row and its type
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: generate-header
+     */
+    generateHeader: GenerateHeaderOptions;
+    private generateHeaderChanged;
+    /**
+     * String that gets applied to the the css gridTemplateColumns attribute of child rows
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: grid-template-columns
+     */
+    gridTemplateColumns: string;
+    private gridTemplateColumnsChanged;
+    /**
+     * The data being displayed in the grid
+     *
+     * @public
+     */
+    rowsData: object[];
+    private rowsDataChanged;
+    /**
+     * The column definitions of the grid
+     *
+     * @public
+     */
+    columnDefinitions: ColumnDefinition[] | null;
+    private columnDefinitionsChanged;
+    /**
+     * The template to use for the programmatic generation of rows
+     *
+     * @public
+     */
+    rowItemTemplate: ViewTemplate;
+    /**
+     * The template used to render cells in generated rows.
+     *
+     * @public
+     */
+    cellItemTemplate?: ViewTemplate;
+    /**
+     * The template used to render header cells in generated rows.
+     *
+     * @public
+     */
+    headerCellItemTemplate?: ViewTemplate;
+    private headerCellItemTemplateChanged;
+    /**
+     * The index of the row that will receive focus the next time the
+     * grid is focused. This value changes as focus moves to different
+     * rows within the grid.  Changing this value when focus is already
+     * within the grid moves focus to the specified row.
+     *
+     * @public
+     */
+    focusRowIndex: number;
+    private focusRowIndexChanged;
+    /**
+     * The index of the column that will receive focus the next time the
+     * grid is focused. This value changes as focus moves to different rows
+     * within the grid.  Changing this value when focus is already within
+     * the grid moves focus to the specified column.
+     *
+     * @public
+     */
+    focusColumnIndex: number;
+    private focusColumnIndexChanged;
+    /**
+     * The default row item template.  Set by the component templates.
+     *
+     * @internal
+     */
+    defaultRowItemTemplate: ViewTemplate;
+    /**
+     * Set by the component templates.
+     *
+     */
+    rowElementTag: string;
+    /**
+     * Children that are rows
+     *
+     * @internal
+     */
+    rowElements: HTMLElement[];
+    private rowsRepeatBehavior;
+    private rowsPlaceholder;
+    private generatedHeader;
+    private isUpdatingFocus;
+    private pendingFocusUpdate;
+    private observer;
+    private rowindexUpdateQueued;
+    private columnDefinitionsStale;
+    private generatedGridTemplateColumns;
+    constructor();
+    /**
+     * @internal
+     */
+    connectedCallback(): void;
+    /**
+     * @internal
+     */
+    disconnectedCallback(): void;
+    /**
+     * @internal
+     */
+    handleRowFocus(e: Event): void;
+    /**
+     * @internal
+     */
+    handleFocus(e: FocusEvent): void;
+    /**
+     * @internal
+     */
+    handleFocusOut(e: FocusEvent): void;
+    /**
+     * @internal
+     */
+    handleKeydown(e: KeyboardEvent): void;
+    private focusOnCell;
+    private queueFocusUpdate;
+    private updateFocus;
+    private toggleGeneratedHeader;
+    private onChildListChange;
+    private queueRowIndexUpdate;
+    private updateRowIndexes;
+}

package/dist/dts/data-grid/data-grid.options.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Enumerates the data grid auto generated header options
+ * default option generates a non-sticky header row
+ *
+ * @public
+ */
+export declare const GenerateHeaderOptions: {
+    readonly none: "none";
+    readonly default: "default";
+    readonly sticky: "sticky";
+};
+/**
+ * The types for the data grid auto generated header options
+ *
+ * @public
+ */
+export type GenerateHeaderOptions = typeof GenerateHeaderOptions[keyof typeof GenerateHeaderOptions];
+/**
+ * Enumerates possible data grid cell types.
+ *
+ * @public
+ */
+export declare const DataGridCellTypes: {
+    readonly default: "default";
+    readonly columnHeader: "columnheader";
+    readonly rowHeader: "rowheader";
+};
+/**
+ * The possible cell types.
+ *
+ * @public
+ */
+export type DataGridCellTypes = typeof DataGridCellTypes[keyof typeof DataGridCellTypes];
+/**
+ * Enumerates possible data grid row types
+ *
+ * @public
+ */
+export declare const DataGridRowTypes: {
+    readonly default: "default";
+    readonly header: "header";
+    readonly stickyHeader: "sticky-header";
+};
+/**
+ * The possible data grid row types
+ *
+ * @public
+ */
+export type DataGridRowTypes = typeof DataGridRowTypes[keyof typeof DataGridRowTypes];

package/dist/dts/data-grid/data-grid.template.d.ts

@@ -0,0 +1,10 @@
+import type { ViewTemplate } from "@ni/fast-element";
+import type { FoundationElementTemplate } from "../foundation-element/foundation-element.js";
+import type { DataGrid } from "./data-grid.js";
+/**
+ * Generates a template for the {@link @ni/fast-foundation#DataGrid} component using
+ * the provided prefix.
+ *
+ * @public
+ */
+export declare const dataGridTemplate: FoundationElementTemplate<ViewTemplate<DataGrid>>;

package/dist/dts/data-grid/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./data-grid.template.js";
+export * from "./data-grid.js";
+export * from "./data-grid-row.template.js";
+export * from "./data-grid-row.js";
+export * from "./data-grid-cell.template.js";
+export * from "./data-grid-cell.js";

package/dist/dts/design-system/component-presentation.d.ts

@@ -0,0 +1,66 @@
+import { ComposableStyles, ElementStyles, ElementViewTemplate, FASTElement } from "@ni/fast-element";
+import { Container } from "../di/di.js";
+/**
+ * Applies presentation details, such as template and styles, to a component instance.
+ * @public
+ */
+export interface ComponentPresentation {
+    /**
+     * Applies the presentation details to the specified element.
+     * @param element - The element to apply the presentation details to.
+     * @public
+     */
+    applyTo(element: FASTElement): void;
+}
+/**
+ * An API gateway to component presentation features.
+ * @public
+ */
+export declare const ComponentPresentation: Readonly<{
+    /**
+     * Defines a component presentation for an element.
+     * @param tagName - The element name to define the presentation for.
+     * @param presentation - The presentation that will be applied to matching elements.
+     * @param container - The dependency injection container to register the configuration in.
+     * @public
+     */
+    define(tagName: string, presentation: ComponentPresentation, container: Container): void;
+    /**
+     * Finds a component presentation for the specified element name,
+     * searching the DOM hierarchy starting from the provided element.
+     * @param tagName - The name of the element to locate the presentation for.
+     * @param element - The element to begin the search from.
+     * @returns The component presentation or null if none is found.
+     * @public
+     */
+    forTag(tagName: string, element: HTMLElement): ComponentPresentation | null;
+}>;
+/**
+ * The default implementation of ComponentPresentation, used by FoundationElement.
+ * @public
+ */
+export declare class DefaultComponentPresentation implements ComponentPresentation {
+    /**
+     * The styles to apply to the element.
+     * @public
+     */
+    readonly styles: ElementStyles | null;
+    /**
+     * The template to apply to the element.
+     * @public
+     */
+    readonly template: ElementViewTemplate | null;
+    /**
+     * Creates an instance of DefaultComponentPresentation.
+     * @param template - The template to apply to the element.
+     * @param styles - The styles to apply to the element.
+     * @public
+     */
+    constructor(template?: ElementViewTemplate, styles?: ComposableStyles | ComposableStyles[]);
+    /**
+     * Applies the presentation details to the specified element.
+     * @param element - The element to apply the presentation details to.
+     * @public
+     */
+    applyTo(element: FASTElement): void;
+}

package/dist/dts/design-system/design-system.d.ts

@@ -0,0 +1,104 @@
+import { Constructable } from "@ni/fast-element";
+/**
+ * Indicates what to do with an ambiguous (duplicate) element.
+ * @public
+ */
+export declare const ElementDisambiguation: Readonly<{
+    /**
+     * Skip defining the element but still call the provided callback passed
+     * to DesignSystemRegistrationContext.tryDefineElement
+     */
+    definitionCallbackOnly: null;
+    /**
+     * Ignore the duplicate element entirely.
+     */
+    ignoreDuplicate: symbol;
+}>;
+/**
+ * Represents the return values expected from an ElementDisambiguationCallback.
+ * @public
+ */
+export type ElementDisambiguationResult = string | typeof ElementDisambiguation.ignoreDuplicate | typeof ElementDisambiguation.definitionCallbackOnly;
+/**
+ * The callback type that is invoked when two elements are trying to define themselves with
+ * the same name.
+ * @remarks
+ * The callback should return either:
+ * 1. A string to provide a new name used to disambiguate the element
+ * 2. ElementDisambiguation.ignoreDuplicate to ignore the duplicate element entirely
+ * 3. ElementDisambiguation.definitionCallbackOnly to skip defining the element but still
+ * call the provided callback passed to DesignSystemRegistrationContext.tryDefineElement
+ * @public
+ */
+export type ElementDisambiguationCallback = (nameAttempt: string, typeAttempt: Constructable, existingType: Constructable) => ElementDisambiguationResult;
+/**
+ * Represents a configurable design system.
+ * @public
+ */
+export interface DesignSystem {
+    /**
+     * Registers components and services with the design system and the
+     * underlying dependency injection container.
+     * @param params - The registries to pass to the design system
+     * and the underlying dependency injection container.
+     * @public
+     */
+    register(...params: any[]): DesignSystem;
+    /**
+     * Configures the prefix to add to each custom element name.
+     * @param prefix - The prefix to use for custom elements.
+     * @public
+     */
+    withPrefix(prefix: string): DesignSystem;
+    /**
+     * Overrides the default Shadow DOM mode for custom elements.
+     * @param mode - The Shadow DOM mode to use for custom elements.
+     * @public
+     */
+    withShadowRootMode(mode: ShadowRootMode): DesignSystem;
+    /**
+     * Provides a custom callback capable of resolving scenarios where
+     * two different elements request the same element name.
+     * @param callback - The disambiguation callback.
+     * @public
+     */
+    withElementDisambiguation(callback: ElementDisambiguationCallback): DesignSystem;
+    /**
+     * Overrides the {@link (DesignToken:interface)} root, controlling where
+     * {@link (DesignToken:interface)} default value CSS custom properties
+     * are emitted.
+     *
+     * Providing `null` disables automatic DesignToken registration.
+     * @param root - the root to register
+     * @public
+     */
+    withDesignTokenRoot(root: HTMLElement | Document | null): DesignSystem;
+}
+/**
+ * An API gateway to design system features.
+ * @public
+ */
+export declare const DesignSystem: Readonly<{
+    /**
+     * Returns the HTML element name that the type is defined as.
+     * @param type - The type to lookup.
+     * @public
+     */
+    tagFor(type: Constructable): string;
+    /**
+     * Searches the DOM hierarchy for the design system that is responsible
+     * for the provided element.
+     * @param element - The element to locate the design system for.
+     * @returns The located design system.
+     * @public
+     */
+    responsibleFor(element: HTMLElement): DesignSystem;
+    /**
+     * Gets the DesignSystem if one is explicitly defined on the provided element;
+     * otherwise creates a design system defined directly on the element.
+     * @param element - The element to get or create a design system for.
+     * @returns The design system.
+     * @public
+     */
+    getOrCreate(node?: Node): DesignSystem;
+}>;

package/dist/dts/design-system/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./design-system.js";
+export * from "./component-presentation.js";
+export * from "./registration-context.js";

package/dist/dts/design-system/registration-context.d.ts

@@ -0,0 +1,106 @@
+import type { Constructable, PartialFASTElementDefinition } from "@ni/fast-element";
+import type { Container } from "../di/di.js";
+import type { ComponentPresentation } from "./component-presentation.js";
+/**
+ * Enables defining an element within the context of a design system.
+ * @public
+ */
+export type ContextualElementDefinition = Omit<PartialFASTElementDefinition, "name">;
+/**
+ * The design system context in which an element can be defined.
+ * @public
+ */
+export interface ElementDefinitionContext {
+    /**
+     * The name that the element will be defined as.
+     * @public
+     */
+    readonly name: string;
+    /**
+     * The type that will be defined.
+     * @public
+     */
+    readonly type: Constructable;
+    /**
+     * The dependency injection container associated with the design system.
+     * @public
+     */
+    readonly container: Container;
+    /**
+     * Indicates whether or not a platform define call will be made in order
+     * to define the element.
+     * @public
+     */
+    readonly willDefine: boolean;
+    /**
+     * The shadow root mode specified by the design system's configuration.
+     * @public
+     */
+    readonly shadowRootMode: ShadowRootMode | undefined;
+    /**
+     * Defines the element.
+     * @param definition - The definition for the element.
+     * @public
+     */
+    defineElement(definition?: ContextualElementDefinition): void;
+    /**
+     * Defines a presentation for the element.
+     * @param presentation - The presentation configuration.
+     * @public
+     */
+    definePresentation(presentation: ComponentPresentation): void;
+    /**
+     * Returns the HTML element tag name that the type will be defined as.
+     * @param type - The type to lookup.
+     * @public
+     */
+    tagFor(type: Constructable): string;
+}
+/**
+ * The callback type that is invoked when an element can be defined by a design system.
+ * @public
+ */
+export type ElementDefinitionCallback = (ctx: ElementDefinitionContext) => void;
+/**
+ * The element definition context interface. Designed to be used in `tryDefineElement`
+ * @public
+ */
+export interface ElementDefinitionParams extends Pick<ElementDefinitionContext, "name" | "type"> {
+    /**
+     * FAST actual base class instance.
+     * @public
+     */
+    readonly baseClass?: Constructable;
+    /**
+     * A callback to invoke if definition will happen.
+     * @public
+     */
+    callback: ElementDefinitionCallback;
+}
+/**
+ * Design system contextual APIs and configuration usable within component
+ * registries.
+ * @public
+ */
+export interface DesignSystemRegistrationContext {
+    /**
+     * The element prefix specified by the design system's configuration.
+     * @public
+     */
+    readonly elementPrefix: string;
+    /**
+     * Used to attempt to define a custom element.
+     * @param name - The name of the element to define.
+     * @param type - The type of the constructor to use to define the element.
+     * @param callback - A callback to invoke if definition will happen.
+     * @public
+     * @deprecated - Use the signature with the ElementDefinitionParams param type instead
+     */
+    tryDefineElement(name: string, type: Constructable, callback: ElementDefinitionCallback): void;
+    /**
+     * Used to attempt to define a custom element.
+     * @param params - The custom element definition.
+     * @public
+     */
+    tryDefineElement(params: ElementDefinitionParams): void;
+}

package/dist/dts/design-token/custom-property-manager.d.ts

@@ -0,0 +1,35 @@
+export declare const defaultElement: HTMLDivElement;
+interface PropertyTarget {
+    setProperty(name: string, value: string | null): void;
+    removeProperty(name: string): void;
+}
+/**
+ * Controls emission for default values. This control is capable
+ * of emitting to multiple {@link PropertyTarget | PropertyTargets},
+ * and only emits if it has at least one root.
+ *
+ * @internal
+ */
+export declare class RootStyleSheetTarget implements PropertyTarget {
+    private static roots;
+    private static properties;
+    setProperty(name: string, value: any): void;
+    removeProperty(name: string): void;
+    static registerRoot(root: HTMLElement | Document): void;
+    static unregisterRoot(root: HTMLElement | Document): void;
+    /**
+     * Returns the document when provided the default element,
+     * otherwise is a no-op
+     * @param root - the root to normalize
+     */
+    private static normalizeRoot;
+}
+/**
+ * Manages creation and caching of PropertyTarget instances.
+ *
+ * @internal
+ */
+export declare const PropertyTargetManager: Readonly<{
+    getOrCreate(source: HTMLElement | Document): PropertyTarget;
+}>;
+export {};