@telesign/boreal-web-components 0.1.0-alpha.0

package/dist/collection/mixins/anchored.mixin.js

@@ -0,0 +1,272 @@
+import { PositioningEngine } from "../services/floating/positioning.service";
+import { floatingMixin } from "./floating.mixin";
+import { Logger } from "../services/logger/Logger";
+import { autoUpdate } from "@floating-ui/dom";
+import { KEYBOARD } from "../utils/constants/common/Keys";
+import { EVENTS } from "../utils/constants/common/Events";
+/**
+ * Positioning and trigger mixin for anchor-based floating elements.
+ *
+ * Extends `floatingMixin` with two additional responsibilities:
+ * - **Positioning** — computes and maintains the position of the floating element
+ *   relative to a trigger element using `IFloatingAdapter` (wraps Floating UI).
+ *   Position is kept in sync via `autoUpdate` while the element is visible.
+ * - **Triggers** — manages DOM event listeners on the trigger element
+ *   (focus/blur, click) to show and hide the floating element.
+ *
+ * Use this mixin for components whose floating element must be anchored
+ * to a specific DOM element: `Tooltip`, `Popover`, `Dropdown`.
+ *
+ * For viewport-relative components (Dialog, Drawer, Toast),
+ * use `backdropMixin` instead.
+ *
+ * ## Lifecycle flow
+ * ```
+ * showElement() → showPopover() + startAutoUpdate()
+ * hideElement() → hidePopover() + stopAutoUpdate()
+ * ```
+ *
+ * ## Required by the component
+ * - `triggerSlot` — must be assigned to the trigger element before `show()` is called.
+ * - `floatingContent` — must be assigned via `ref` in the render method.
+ * - `options` — override this getter to customize placement, offset and strategy.
+ *
+ * @example
+ * ```typescript
+ * import { Component, Element, Mixin, Prop, h } from '@stencil/core';
+ * import { anchoredMixin } from '@/mixins/anchored.mixin';
+ * import { FloatingHooks, FloatingMixinOptions } from '@/services/floating/interfaces/Floating';
+ *
+ * @Component({ tag: 'bds-tooltip' })
+ * export class BdsTooltip extends Mixin(anchoredMixin) {
+ *
+ *   get options(): FloatingMixinOptions {
+ *     return { placement: 'bottom', offset: 8, strategy: 'fixed' };
+ *   }
+ *
+ *   get hooks(): FloatingHooks {
+ *     return {
+ *       onBeforeShow: () => !this.disabled,
+ *       onPositionUpdate: result => this.handlePosition(result),
+ *     };
+ *   }
+ *
+ *   componentDidLoad() {
+ *     const trigger = document.getElementById(this.trigger);
+ *     if (trigger) {
+ *       this.triggerSlot = trigger;
+ *       trigger.addEventListener('click', () => this.toggle());
+ *     }
+ *   }
+ *
+ *   render() {
+ *     return (
+ *       <Host>
+ *         <div
+ *           popover="manual"
+ *           ref={el => (this.floatingContent = el as HTMLElement)}
+ *         />
+ *       </Host>
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @see floatingMixin - base lifecycle mixin
+ * @see IFloatingAdapter - positioning adapter interface
+ * @see FloatingMixinOptions - positioning configuration interface
+ * @see FloatingHooks - lifecycle hook interface, includes `onPositionUpdate`
+ */
+export const anchoredMixin = (Base) => {
+    class Anchored extends floatingMixin(Base) {
+        /**
+         * Default positioning options.
+         * Override this getter in the component to customize placement,
+         * offset, strategy, flip, shift, and arrow.
+         */
+        get options() {
+            return { placement: 'bottom', offset: 8, strategy: 'fixed' };
+        }
+        /**
+         * Shows the floating element using the Popover API
+         * and starts position auto-update relative to `triggerSlot`.
+         *
+         * @override floatingMixin.showElement
+         */
+        showElement() {
+            this.floatingContent.showPopover();
+            this.isVisible = true;
+            this.startAutoUpdate(this.triggerSlot, this.floatingContent, this.options, result => {
+                this.hooks.onPositionUpdate?.(result);
+            });
+        }
+        /**
+         * Guards against showing without a valid trigger.
+         * Delegates to `floatingMixin.onBeforeShow` if the guard passes.
+         *
+         * @override floatingMixin.onBeforeShow
+         * @param target - Optional element that triggered the show action
+         * @returns `false` if `triggerSlot` is not set, otherwise delegates to super
+         */
+        onBeforeShow(target) {
+            if (this.triggerSlot === null) {
+                this.logger.error('AnchoredMixin.show', 'triggerSlot is required');
+                return false;
+            }
+            return super.onBeforeShow(target);
+        }
+        /**
+         * Hides the floating element using the Popover API
+         * and stops position auto-update.
+         *
+         * @override floatingMixin.hideElement
+         */
+        hideElement() {
+            this.stopAutoUpdate();
+            this.floatingContent?.hidePopover();
+            this.isVisible = false;
+        }
+        /**
+         * Handles slot change events to update the trigger element reference
+         * and re-attach event listeners to the new trigger.
+         *
+         * @param e - The slot change event
+         * @param showFn - Bound show function to attach as listener
+         * @param hideFn - Bound hide function to attach as listener
+         */
+        handleSlotChange(e, showFn, hideFn) {
+            const newTrigger = e.target;
+            if (this.previousTrigger !== undefined && this.previousTrigger !== null) {
+                this.detachTriggerListeners(this.previousTrigger, showFn, hideFn);
+            }
+            if (newTrigger !== undefined && newTrigger !== null) {
+                this.attachTriggerListeners(newTrigger, showFn, hideFn);
+                this.previousTrigger = newTrigger;
+            }
+        }
+        /**
+         * Handles keyboard events on the trigger element.
+         * - `Enter` / `Space` — shows the floating element
+         * - `Escape` — hides the floating element
+         *
+         * @param e - The keyboard event
+         * @param showFn - Bound show function
+         * @param hideFn - Bound hide function
+         */
+        handleKeydown(e, showFn, hideFn) {
+            if (e.key === KEYBOARD.Enter.key || e.key === ' ')
+                showFn();
+            if (e.key === KEYBOARD.Escape.key)
+                hideFn();
+        }
+        /**
+         * Computes the position of the floating element relative to the trigger
+         * using `IFloatingAdapter` and applies the result to the floating element's style.
+         *
+         * @param triggerElement - The anchor element
+         * @param floatingElement - The element to position
+         * @param options - Positioning options (placement, offset, flip, shift, arrow)
+         * @param onPositionUpdate - Optional callback invoked after each position update
+         */
+        async updatePosition(triggerElement, floatingElement, options, onPositionUpdate) {
+            const result = await this.positionEngine.computePosition(triggerElement, floatingElement, {
+                placement: options.placement,
+                offset: options.offset,
+                flip: options.flip ?? true,
+                shift: options.shift ?? true,
+                arrow: options.arrow,
+                strategy: options.strategy ?? 'fixed',
+            });
+            this.positionEngine.applyPosition(floatingElement, result);
+            onPositionUpdate?.(result);
+            return result;
+        }
+        /**
+         * Starts automatic position synchronization between the trigger
+         * and the floating element. Runs `updatePosition` once immediately,
+         * then subscribes to DOM/scroll/resize changes via `autoUpdate`.
+         *
+         * @param triggerElement - The anchor element
+         * @param floatingElement - The element to keep in sync
+         * @param options - Positioning options
+         * @param onPositionUpdate - Optional callback after each position update
+         */
+        startAutoUpdate(triggerElement, floatingElement, options, onPositionUpdate) {
+            const sync = () => {
+                void this.updatePosition(triggerElement, floatingElement, options, onPositionUpdate);
+            };
+            sync(); // run once immediately
+            this.cleanupAutoUpdate = autoUpdate(triggerElement, floatingElement, sync);
+        }
+        /**
+         * Stops automatic position synchronization and clears the cleanup reference.
+         */
+        stopAutoUpdate() {
+            this.cleanupAutoUpdate?.();
+            this.cleanupAutoUpdate = undefined;
+        }
+        /**
+         * Attaches focus and blur listeners to the trigger element.
+         *
+         * @param trigger - The trigger element
+         * @param showFn - Bound show function
+         * @param hideFn - Bound hide function
+         */
+        attachTriggerListeners(trigger, showFn, hideFn) {
+            trigger.addEventListener(EVENTS.Focus, showFn);
+            trigger.addEventListener(EVENTS.Blur, hideFn);
+        }
+        /**
+         * Detaches focus and blur listeners from the trigger element.
+         *
+         * @param trigger - The trigger element
+         * @param showFn - Bound show function to remove
+         * @param hideFn - Bound hide function to remove
+         */
+        detachTriggerListeners(trigger, showFn, hideFn) {
+            trigger.removeEventListener(EVENTS.Focus, showFn);
+            trigger.removeEventListener(EVENTS.Blur, hideFn);
+        }
+        /**
+         * Detaches trigger listeners and stops auto-update.
+         * Call this when the component disconnects from the DOM.
+         *
+         * @param showFn - Bound show function to remove
+         * @param hideFn - Bound hide function to remove
+         */
+        floatingDisconnect(showFn, hideFn) {
+            if (this.previousTrigger !== undefined && this.previousTrigger !== null) {
+                this.detachTriggerListeners(this.previousTrigger, showFn, hideFn);
+            }
+            this.stopAutoUpdate();
+        }
+        /**
+         * Initializes the positioning engine, logger, and binds lifecycle methods
+         * so they can be safely passed as event listener callbacks.
+         *
+         * @remarks `show`, `hide`, and `toggle` are bound here — not in `floatingMixin` —
+         * to ensure they resolve to the `anchoredMixin` overrides at call time.
+         */
+        componentWillLoad() {
+            this.toggle = this.toggle.bind(this);
+            this.show = this.show.bind(this);
+            this.hide = this.hide.bind(this);
+            this.positionEngine = new PositioningEngine();
+            this.logger = new Logger();
+            this.cleanupAutoUpdate = undefined;
+            this.previousTrigger = undefined;
+        }
+        /**
+         * Cleans up trigger listeners, stops auto-update, and hides the floating element
+         * when the component is removed from the DOM.
+         */
+        disconnectedCallback() {
+            if (this.previousTrigger !== undefined && this.previousTrigger !== null) {
+                this.floatingDisconnect(() => this.show(), () => this.hide());
+            }
+            this.stopAutoUpdate();
+            this.hide();
+        }
+    }
+    return Anchored;
+};

package/dist/collection/mixins/floating.mixin.js

@@ -0,0 +1,181 @@
+/**
+ * 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(),
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export 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 {};
+        }
+        /**
+         * 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;
+};

package/dist/collection/mixins/form-associated.mixin.js

@@ -0,0 +1,95 @@
+/**
+ * Shared base mixin for Form-Associated Custom Elements in Boreal DS.
+ *
+ * Provides:
+ * - `name`, `disabled`, and `required` form props
+ * - `formDisabledCallback` with universal disabled sync behavior
+ *
+ * Each component must declare `@AttachInternals() internals!: ElementInternals`
+ * directly on its class body — Stencil's compiler requires this decorator to be
+ * statically visible on the component class, not inside a mixin factory.
+ *
+ * Components must also implement `IFormControl<T>` for value registration,
+ * reset, state restoration, and 2-way binding event emission.
+ */
+export const formAssociatedMixin = (Base) => {
+    class FormAssociated extends Base {
+        constructor() {
+            /** Disables the control. Synced automatically from a parent `<fieldset>` or `<form>` via `formDisabledCallback`. */
+            this.disabled = false;
+            /** Marks the control as required for form submission. */
+            this.required = false;
+            super();
+        }
+        /**
+         * Sync component disabled state with parent form disabled state.
+         */
+        formDisabledCallback(disabled) {
+            this.disabled = disabled;
+        }
+        static get properties() {
+            return {
+                "name": {
+                    "type": "string",
+                    "mutable": false,
+                    "complexType": {
+                        "original": "string",
+                        "resolved": "string",
+                        "references": {}
+                    },
+                    "required": true,
+                    "optional": false,
+                    "docs": {
+                        "tags": [],
+                        "text": "Name of the form control, submitted as a key in the form data."
+                    },
+                    "getter": false,
+                    "setter": false,
+                    "reflect": true,
+                    "attribute": "name"
+                },
+                "disabled": {
+                    "type": "boolean",
+                    "mutable": true,
+                    "complexType": {
+                        "original": "boolean",
+                        "resolved": "boolean",
+                        "references": {}
+                    },
+                    "required": false,
+                    "optional": false,
+                    "docs": {
+                        "tags": [],
+                        "text": "Disables the control. Synced automatically from a parent `<fieldset>` or `<form>` via `formDisabledCallback`."
+                    },
+                    "getter": false,
+                    "setter": false,
+                    "reflect": true,
+                    "attribute": "disabled",
+                    "defaultValue": "false"
+                },
+                "required": {
+                    "type": "boolean",
+                    "mutable": false,
+                    "complexType": {
+                        "original": "boolean",
+                        "resolved": "boolean",
+                        "references": {}
+                    },
+                    "required": false,
+                    "optional": false,
+                    "docs": {
+                        "tags": [],
+                        "text": "Marks the control as required for form submission."
+                    },
+                    "getter": false,
+                    "setter": false,
+                    "reflect": true,
+                    "attribute": "required",
+                    "defaultValue": "false"
+                }
+            };
+        }
+    }
+    return FormAssociated;
+};

package/dist/collection/mixins/index.js

@@ -0,0 +1,3 @@
+export * from './form-associated.mixin';
+export * from './floating.mixin';
+export * from './anchored.mixin';

package/dist/collection/scss/global/_fonts.scss

@@ -0,0 +1 @@
+@import url('https://fonts.googleapis.com/css2?family=Courier+Prime:ital,wght@0,400;0,700;1,400;1,700&family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap');

package/dist/collection/scss/global/_index.scss

@@ -0,0 +1,3 @@
+@forward '_fonts';
+@forward '_typography';
+@forward '_reset';

package/dist/collection/scss/global/_reset.scss

@@ -0,0 +1,50 @@
+/**
+ * Boreal Design System - CSS Reset
+ * Minimal reset for consistent cross-browser rendering
+ */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+* {
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  line-height: 1.5;
+  -webkit-text-size-adjust: 100%;
+}
+
+img,
+picture,
+video,
+canvas,
+svg {
+  display: block;
+  max-width: 100%;
+}
+
+input,
+button,
+textarea,
+select {
+  font: inherit;
+}
+
+p,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  overflow-wrap: break-word;
+}