@telesign/boreal-web-components 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/cjs/floating.mixin-Bje4320w.js

@@ -0,0 +1,195 @@
+'use strict';
+
+/**
+ * Core lifecycle mixin for all floating elements in the design system.
+ *
+ * Provides a unified lifecycle contract (`show`, `hide`, `toggle`, `isVisible`)
+ * and an extension mechanism via `FloatingHooks` that allows each component
+ * to inject its own logic at specific lifecycle points without modifying the mixin.
+ *
+ * This mixin is the base for all floating components. It does not handle
+ * positioning or triggers — use `anchoredMixin` for components that need
+ * to be anchored to a DOM element (Tooltip, Popover),
+ * or `backdropMixin` for viewport-relative components (Dialog, Drawer, Toast).
+ *
+ * ## Extension points
+ *
+ * Override `showElement` / `hideElement` to control how the element
+ * mounts and unmounts (e.g. `showPopover()`, `showModal()`, CSS animations).
+ *
+ * Override `hooks` to inject logic at lifecycle points:
+ * - `onBeforeShow` / `onBeforeHide` — return `false` to cancel the action
+ * - `onAfterShow` / `onAfterHide` — side effects after the action completes
+ * - `mounted` / `unmounted` — called after the element is shown or hidden
+ *
+ * ## Lifecycle flow
+ * ```
+ * show(): onBeforeShow() → showElement() → onAfterShow()
+ * hide(): onBeforeHide() → hideElement() → onAfterHide()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { Component, Mixin, Prop } from '@stencil/core';
+ * import { floatingMixin } from '@/mixins/floating.mixin';
+ * import { FloatingHooks } from '@/services/floating/interfaces/Floating';
+ *
+ * @Component({ tag: 'bds-dialog' })
+ * export class BdsDialog extends Mixin(floatingMixin) {
+ *   private dialogElement!: HTMLDialogElement;
+ *
+ *   // Override showElement/hideElement to use the native <dialog> API
+ *   showElement(): void {
+ *     this.dialogElement.showModal();
+ *     this.isVisible = true;
+ *   }
+ *   hideElement(): void {
+ *     this.dialogElement.close();
+ *     this.isVisible = false;
+ *   }
+ *
+ *   // Inject component-specific logic via hooks
+ *   get hooks(): FloatingHooks {
+ *     return {
+ *       onBeforeShow: () => !this.disabled,
+ *       onAfterShow: () => this.lockScroll(),
+ *       onAfterHide: () => this.unlockScroll(),
+ *     };
+ *   }
+ * }
+ * ```
+ */
+const floatingMixin = (Base) => {
+    class Floating extends Base {
+        constructor() {
+            super();
+        }
+        /**
+         * Lifecycle hooks provided by the component.
+         * Override this getter to inject component-specific logic
+         * into the floating lifecycle without modifying the mixin.
+         *
+         * @returns FloatingHooks — an object with optional lifecycle callbacks
+         */
+        get hooks() {
+            return {};
+        }
+        /**
+         * Default options for the floating mixin.
+         * Override this getter in the component to customize placement,
+         * offset, strategy, flip, shift, and arrow.
+         *
+         * @returns FloatingMixinOptions — default options for the mixin
+         */
+        get options() {
+            return {};
+        }
+        /**
+         * Called before the element is shown.
+         * Aggregates both the component `hooks` and `floatingOptions` controls.
+         * If either returns `false`, the show action is cancelled.
+         *
+         * @param target - Optional element that triggered the show action
+         * @returns `true` if the element can be shown, `false` to cancel
+         */
+        onBeforeShow(target) {
+            const hookControl = this.hooks.onBeforeShow?.(target) ?? true;
+            const propControl = this.floatingOptions?.onBeforeShow?.(target) ?? true;
+            return hookControl && propControl;
+        }
+        /**
+         * Called before the element is hidden.
+         * Aggregates both the component `hooks` and `floatingOptions` controls.
+         * If either returns `false`, the hide action is cancelled.
+         *
+         * @param target - Optional element the mouse moved to (used for stayOnHover logic)
+         * @returns `true` if the element can be hidden, `false` to cancel
+         */
+        onBeforeHide(target) {
+            const hookControl = this.hooks.onBeforeHide?.(target) ?? true;
+            const propControl = this.floatingOptions?.onBeforeHide?.(target) ?? true;
+            return hookControl && propControl;
+        }
+        /**
+         * Mounts the floating element into the visible DOM.
+         * Override in subclasses to use a different mount strategy
+         * (e.g. `showPopover()`, `showModal()`, CSS class toggle).
+         */
+        showElement() {
+            this.isVisible = true;
+            this.hooks.mounted?.(this.floatingContent);
+        }
+        /**
+         * Unmounts the floating element from the visible DOM.
+         * Override in subclasses to use a different unmount strategy.
+         */
+        hideElement() {
+            this.isVisible = false;
+            this.hooks.unmounted?.(this.floatingContent);
+        }
+        /**
+         * Shows the floating element if not already visible.
+         * Runs the full lifecycle: `onBeforeShow` → `showElement` → `onAfterShow`.
+         *
+         * @param target - Optional element that triggered the action
+         */
+        show(target) {
+            if (this.isVisible)
+                return;
+            if (!this.onBeforeShow(target))
+                return;
+            this.showElement();
+            this.onAfterShow(target);
+        }
+        /**
+         * Hides the floating element if currently visible.
+         * Runs the full lifecycle: `onBeforeHide` → `hideElement` → `onAfterHide`.
+         *
+         * @param target - Optional element the mouse moved to
+         */
+        hide(target) {
+            if (!this.isVisible)
+                return;
+            if (!this.onBeforeHide(target))
+                return;
+            this.hideElement();
+            this.onAfterHide(target);
+        }
+        /**
+         * Toggles the floating element visibility.
+         *
+         * @param target - Optional element that triggered the action
+         */
+        toggle(target) {
+            this.isVisible ? this.hide(target) : this.show();
+        }
+        /**
+         * Called after the element is shown.
+         * Notifies both `hooks` and `floatingOptions` consumers.
+         *
+         * @param target - Optional element that triggered the action
+         */
+        onAfterShow(target) {
+            this.hooks.onAfterShow?.(target);
+            this.floatingOptions?.onAfterShow?.(target);
+        }
+        /**
+         * Called after the element is hidden.
+         * Notifies both `hooks` and `floatingOptions` consumers.
+         *
+         * @param target - Optional element that triggered the action
+         */
+        onAfterHide(target) {
+            this.hooks.onAfterHide?.(target);
+            this.floatingOptions?.onAfterHide?.(target);
+        }
+        static get states() {
+            return {
+                "isVisible": {}
+            };
+        }
+    }
+    return Floating;
+};
+
+exports.floatingMixin = floatingMixin;

package/dist/cjs/form-associated.mixin-DXwvF_vW.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * Registers the component's current value with the browser's form machinery.
+ *
+ * Wraps `ElementInternals.setFormValue()` so the value appears in `FormData`
+ * under the component's `name` attribute when the form is submitted.
+ * Pass `null` to remove the component's contribution from `FormData`
+ * (e.g. an unchecked checkbox).
+ *
+ * @param internals - The component's `ElementInternals` instance (from `@AttachInternals()`).
+ * @param value - The value to register, or `null` to deregister.
+ *
+ * @example
+ * ```typescript
+ * // Register a string value on every value change
+ * @Watch('value')
+ * onValueChange(next: string) {
+ *   setFormValue(this.internals, next);
+ * }
+ *
+ * // Deregister when unchecked
+ * setFormValue(this.internals, null);
+ * ```
+ */
+function setFormValue(internals, value) {
+    internals.setFormValue?.(value);
+}
+/**
+ * Runs an array of validators against the host element and reports the combined
+ * result to `ElementInternals.setValidity()`.
+ *
+ * All validators are evaluated regardless of order. The first failing validator's
+ * message is used as the validation message, matching native browser behaviour
+ * (one message surfaced at a time). When all validators pass, the component is
+ * marked valid and any previous invalid state is cleared.
+ *
+ * @param internals - The component's `ElementInternals` instance (from `@AttachInternals()`).
+ * @param validators - Array of `IFormValidator` objects to evaluate.
+ * @param el - The host element passed to each validator's `isValid` function.
+ * @returns `true` if all validators pass, `false` if any fail.
+ *
+ * @example
+ * ```typescript
+ * private get validators(): IFormValidator[] {
+ *   return [
+ *     {
+ *       key: 'valueMissing',
+ *       isValid: (el) => !(el as BdsTextField).required || (el as BdsTextField).value !== '',
+ *       message: 'This field is required.',
+ *     },
+ *     {
+ *       key: 'tooShort',
+ *       isValid: (el) => {
+ *         const { value, minLength } = el as BdsTextField;
+ *         return minLength === undefined || value.length >= minLength;
+ *       },
+ *       message: `Minimum length not reached.`,
+ *     },
+ *   ];
+ * }
+ *
+ * private updateValidity() {
+ *   runValidators(this.internals, this.validators, this.el);
+ * }
+ * ```
+ */
+function runValidators(internals, validators, el) {
+    const flags = {};
+    let firstMessage = '';
+    for (const { key, isValid, message } of validators) {
+        if (!isValid(el)) {
+            flags[key] = true;
+            if (firstMessage === '')
+                firstMessage = message;
+        }
+    }
+    const valid = Object.keys(flags).length === 0;
+    internals.setValidity?.(valid ? {} : flags, firstMessage);
+    return valid;
+}
+
+/**
+ * Shared base mixin for Form-Associated Custom Elements in Boreal DS.
+ *
+ * Provides `formDisabledCallback` — the only behavior that is identical across
+ * all FACE components. It writes to the component's `isDisabled` state, which
+ * each component must declare as `@State() private isDisabled: boolean = false`.
+ *
+ * Each component must declare directly on its class body:
+ * - `@AttachInternals() internals!: ElementInternals`
+ * - `@Prop({ reflect: true }) readonly name!: string`
+ * - `@Prop({ reflect: true }) readonly disabled: boolean = false`
+ * - `@Prop({ reflect: true }) readonly required: boolean = false`
+ * - `@State() private isDisabled: boolean = false`
+ * - `@Watch('disabled') onDisabledChange(next: boolean) { this.isDisabled = next; }`
+ *
+ * Stencil's compiler requires `@Prop` and `@State` decorators to be statically
+ * visible on the component class — they cannot be inherited from a mixin.
+ *
+ * Components must also implement `IFormControl<T>` for value registration,
+ * reset, state restoration, and 2-way binding event emission.
+ */
+const formAssociatedMixin = (Base) => {
+    class FormAssociated extends Base {
+        formDisabledCallback(disabled) {
+            this.isDisabled = disabled;
+        }
+    }
+    return FormAssociated;
+};
+
+exports.formAssociatedMixin = formAssociatedMixin;
+exports.runValidators = runValidators;
+exports.setFormValue = setFormValue;