@jackuait/blok 0.4.1-beta.5 → 0.4.1-beta.6

package/src/components/utils/placeholder.ts

@@ -0,0 +1,140 @@
+/**
+ * Placeholder utilities for contenteditable elements
+ *
+ * Provides unified handling for:
+ * - Placeholder styling classes
+ * - Caret positioning when content is empty
+ * - Focus and input event handlers
+ *
+ * @license MIT
+ */
+
+/**
+ * Placeholder styling classes using Tailwind arbitrary variants.
+ * Applied to ::before pseudo-element only when element is empty.
+ * Uses data-placeholder attribute for the placeholder text.
+ */
+export const PLACEHOLDER_CLASSES: string[] = [
+  'empty:before:pointer-events-none',
+  'empty:before:text-gray-text',
+  'empty:before:cursor-text',
+  'empty:before:content-[attr(data-placeholder)]',
+  '[&[data-blok-empty=true]]:before:pointer-events-none',
+  '[&[data-blok-empty=true]]:before:text-gray-text',
+  '[&[data-blok-empty=true]]:before:cursor-text',
+  '[&[data-blok-empty=true]]:before:content-[attr(data-placeholder)]',
+];
+
+/**
+ * Alternative placeholder classes using data-blok-placeholder-active attribute.
+ * Used by some tools that need a different attribute name.
+ */
+export const PLACEHOLDER_ACTIVE_CLASSES: string[] = [
+  'empty:before:pointer-events-none',
+  'empty:before:text-gray-text',
+  'empty:before:cursor-text',
+  'empty:before:content-[attr(data-blok-placeholder-active)]',
+  '[&[data-empty=true]]:before:pointer-events-none',
+  '[&[data-empty=true]]:before:text-gray-text',
+  '[&[data-empty=true]]:before:cursor-text',
+  '[&[data-empty=true]]:before:content-[attr(data-blok-placeholder-active)]',
+];
+
+/**
+ * Placeholder classes that only show placeholder when element is focused.
+ * Uses data-blok-placeholder-active attribute and only displays when element is empty AND focused.
+ * Used by paragraph tool.
+ */
+export const PLACEHOLDER_FOCUS_ONLY_CLASSES: string[] = [
+  'empty:focus:before:pointer-events-none',
+  'empty:focus:before:text-gray-text',
+  'empty:focus:before:cursor-text',
+  'empty:focus:before:content-[attr(data-blok-placeholder-active)]',
+  '[&[data-empty=true]:focus]:before:pointer-events-none',
+  '[&[data-empty=true]:focus]:before:text-gray-text',
+  '[&[data-empty=true]:focus]:before:cursor-text',
+  '[&[data-empty=true]:focus]:before:content-[attr(data-blok-placeholder-active)]',
+];
+
+/**
+ * Check if an element's content is empty
+ *
+ * @param element - The element to check
+ * @returns true if the element is empty or contains only a <br>
+ */
+export const isContentEmpty = (element: HTMLElement): boolean => {
+  const content = element.innerHTML.trim();
+  return content === '' || content === '<br>';
+};
+
+/**
+ * Set caret to the start of an element.
+ * Clears any <br> tags to ensure clean empty state for placeholder.
+ *
+ * @param element - The element to set caret in
+ */
+export const setCaretToStart = (element: HTMLElement): void => {
+  // Clear any <br> tags to ensure clean empty state for placeholder
+  if (element.innerHTML === '<br>') {
+    // eslint-disable-next-line no-param-reassign
+    element.innerHTML = '';
+  }
+
+  const selection = window.getSelection();
+  if (!selection) return;
+
+  const range = document.createRange();
+  range.selectNodeContents(element);
+  range.collapse(true);
+  selection.removeAllRanges();
+  selection.addRange(range);
+};
+
+/**
+ * Handler that sets caret to start when element is empty.
+ * Used for focus and input events.
+ *
+ * @param element - The element to handle
+ */
+const handleEmptyElement = (element: HTMLElement): void => {
+  if (!isContentEmpty(element)) return;
+  setCaretToStart(element);
+};
+
+/**
+ * Set up placeholder behavior for a contenteditable element.
+ * Adds focus and input event listeners to handle caret positioning
+ * when the element is empty.
+ *
+ * @param element - The contenteditable element
+ * @param placeholder - Optional placeholder text to set
+ * @param attributeName - The attribute name for placeholder text (default: 'data-placeholder')
+ */
+export const setupPlaceholder = (
+  element: HTMLElement,
+  placeholder?: string,
+  attributeName: 'data-placeholder' | 'data-blok-placeholder-active' = 'data-placeholder'
+): void => {
+  // Always set the attribute, even if empty (for consistency and testing)
+  element.setAttribute(attributeName, placeholder ?? '');
+
+  const handler = (): void => handleEmptyElement(element);
+
+  element.addEventListener('focus', handler);
+  element.addEventListener('input', handler);
+};
+
+/**
+ * Apply placeholder attribute to an element
+ *
+ * @param element - The element to apply placeholder to
+ * @param placeholder - The placeholder text
+ * @param attributeName - The attribute name (default: 'data-placeholder')
+ */
+export const applyPlaceholderAttribute = (
+  element: HTMLElement,
+  placeholder: string,
+  attributeName: 'data-placeholder' | 'data-blok-placeholder-active' = 'data-placeholder'
+): void => {
+  element.setAttribute(attributeName, placeholder);
+};

package/src/components/utils/popover/components/hint/hint.const.ts

@@ -0,0 +1,10 @@
+/**
+ * CSS class names to be used in hint class
+ */
+export const css = {
+  root: '',
+  alignedStart: 'text-start',
+  alignedCenter: 'text-center',
+  title: '',
+  description: 'opacity-60 mt-[3px]',
+};

package/src/components/utils/popover/components/hint/hint.ts

@@ -0,0 +1,46 @@
+import { Dom } from '../../../../dom';
+import { css } from './hint.const';
+import type { HintParams } from '@/types/utils/popover/hint';
+
+/**
+ * Represents the hint content component
+ */
+export class Hint {
+  /**
+   * Html element used to display hint content on screen
+   */
+  private nodes: {
+    root: HTMLElement;
+    title: HTMLElement;
+    description?: HTMLElement;
+  };
+
+  /**
+   * Constructs the hint content instance
+   * @param params - hint content parameters
+   */
+  constructor(params: HintParams) {
+    const alignment = params.alignment === 'center' ? 'center' : 'start';
+
+    this.nodes = {
+      root: Dom.make('div', [css.root, alignment === 'center' ? css.alignedCenter : css.alignedStart]),
+      title: Dom.make('div', css.title, { textContent: params.title }),
+    };
+
+    this.nodes.root.setAttribute('data-alignment', alignment);
+    this.nodes.root.appendChild(this.nodes.title);
+
+    if (params.description !== undefined) {
+      this.nodes.description = Dom.make('div', css.description, { textContent: params.description });
+
+      this.nodes.root.appendChild(this.nodes.description);
+    }
+  }
+
+  /**
+   * Returns the root element of the hint content
+   */
+  public getElement(): HTMLElement {
+    return this.nodes.root;
+  }
+}

package/src/components/utils/popover/components/hint/index.ts

@@ -0,0 +1,6 @@
+export * from './hint';
+export type {
+  HintParams,
+  HintPosition,
+  HintTextAlignment
+} from '@/types/utils/popover/hint';

package/src/components/utils/popover/components/popover-header/index.ts

@@ -0,0 +1,2 @@
+export * from './popover-header';
+export type * from './popover-header.types';

package/src/components/utils/popover/components/popover-header/popover-header.const.ts

@@ -0,0 +1,8 @@
+/**
+ * Tailwind CSS classes for popover header component
+ */
+export const css = {
+  root: 'flex items-center mb-2 mt-1',
+  text: 'text-lg font-semibold text-text-primary',
+  backButton: 'border-0 bg-transparent w-9 h-9 text-text-primary cursor-pointer [&_svg]:block [&_svg]:w-7 [&_svg]:h-7',
+};

package/src/components/utils/popover/components/popover-header/popover-header.ts

@@ -0,0 +1,80 @@
+import type { PopoverHeaderParams } from './popover-header.types';
+import { Dom } from '../../../../dom';
+import { css } from './popover-header.const';
+import { DATA_ATTR } from '../../../../constants/data-attributes';
+import { IconChevronLeft } from '../../../../icons';
+import { Listeners } from '../../../listeners';
+
+/**
+ * Represents popover header ui element
+ */
+export class PopoverHeader {
+  /**
+   * Listeners util instance
+   */
+  private listeners = new Listeners();
+
+  /**
+   * Header html elements
+   */
+  private nodes: {
+      root: HTMLElement,
+      text: HTMLElement,
+      backButton: HTMLElement
+    };
+
+  /**
+   * Text displayed inside header
+   */
+  private readonly text: string;
+
+  /**
+   * Back button click handler
+   */
+  private readonly onBackButtonClick: () => void;
+
+  /**
+   * Constructs the instance
+   * @param params - popover header params
+   */
+  constructor({ text, onBackButtonClick }: PopoverHeaderParams) {
+    this.text = text;
+    this.onBackButtonClick = onBackButtonClick;
+
+    this.nodes = {
+      root: Dom.make('div', [ css.root ], {
+        'data-blok-testid': 'popover-header',
+        [DATA_ATTR.popoverHeader]: '',
+      }),
+      backButton: Dom.make('button', [ css.backButton ], {
+        'data-blok-testid': 'popover-header-back-button',
+        [DATA_ATTR.popoverHeaderBackButton]: '',
+      }),
+      text: Dom.make('div', [ css.text ], {
+        'data-blok-testid': 'popover-header-text',
+        [DATA_ATTR.popoverHeaderText]: '',
+      }),
+    };
+    this.nodes.backButton.innerHTML = IconChevronLeft;
+    this.nodes.root.appendChild(this.nodes.backButton);
+    this.listeners.on(this.nodes.backButton, 'click', this.onBackButtonClick);
+
+    this.nodes.text.innerText = this.text;
+    this.nodes.root.appendChild(this.nodes.text);
+  }
+
+  /**
+   * Returns popover header root html element
+   */
+  public getElement(): HTMLElement | null {
+    return this.nodes.root;
+  }
+
+  /**
+   * Destroys the instance
+   */
+  public destroy(): void {
+    this.nodes.root.remove();
+    this.listeners.destroy();
+  }
+}

package/src/components/utils/popover/components/popover-header/popover-header.types.ts

@@ -0,0 +1,14 @@
+/**
+ * Popover header params
+ */
+export interface PopoverHeaderParams {
+  /**
+   * Text to be displayed inside header
+   */
+  text: string;
+
+  /**
+   * Back button click handler
+   */
+  onBackButtonClick: () => void;
+}

package/src/components/utils/popover/components/popover-item/index.ts

@@ -0,0 +1,13 @@
+import { PopoverItemDefault } from './popover-item-default/popover-item-default';
+import { PopoverItemSeparator } from './popover-item-separator/popover-item-separator';
+import { PopoverItem } from './popover-item';
+
+export * from './popover-item-default/popover-item-default.const';
+export type * from '@/types/utils/popover/popover-item.d.ts';
+export { PopoverItemType } from '@/types/utils/popover/popover-item-type';
+
+export {
+  PopoverItemDefault,
+  PopoverItemSeparator,
+  PopoverItem
+};

package/src/components/utils/popover/components/popover-item/popover-item-default/popover-item-default.const.ts

@@ -0,0 +1,50 @@
+/**
+ * Tailwind CSS class names for popover item
+ */
+export const css = {
+  /**
+   * Base item styles with hover, focus, and active support
+   * Hover is applied via can-hover:hover: for real hover and data-blok-force-hover for tests
+   * Focus is applied via data-blok-focused attribute (set by DomIterator during keyboard navigation)
+   * Active is applied via data-blok-popover-item-active attribute
+   * Note: noHover state is handled via [data-blok-popover-item-no-hover] which disables hover
+   * Priority order: active < hover < focus (focus wins when navigating with keyboard)
+   */
+  item: 'flex items-center select-none border-none bg-transparent rounded-md p-[var(--item-padding)] text-text-primary mb-px [&[data-blok-popover-item-active]]:bg-icon-active-bg [&[data-blok-popover-item-active]]:text-icon-active-text can-hover:hover:cursor-pointer can-hover:hover:bg-item-hover-bg [&[data-blok-force-hover]]:cursor-pointer [&[data-blok-force-hover]]:bg-item-hover-bg [&[data-blok-focused="true"]]:bg-item-focus-bg [&[data-blok-popover-item-no-hover]]:hover:bg-transparent [&[data-blok-popover-item-no-hover]]:cursor-default',
+
+  /**
+   * Item disabled state
+   */
+  itemDisabled: 'cursor-default pointer-events-none text-text-secondary',
+
+  /**
+   * Icon container styles
+   */
+  icon: 'flex items-center justify-center w-[26px] h-[26px] [&_svg]:w-icon [&_svg]:h-icon',
+
+  /**
+   * Focused state class for DomIterator/Flipper keyboard navigation.
+   * Used alongside data-blok-focused attribute.
+   */
+  focused: 'is-focused',
+};
+
+/**
+ * Tailwind CSS class names for inline popover item
+ */
+export const cssInline = {
+  /**
+   * Item in inline context - more compact styling
+   */
+  item: 'rounded p-1',
+};
+
+/**
+ * Tailwind CSS class names for nested inline popover item
+ */
+export const cssNestedInline = {
+  /**
+   * Nested item - back to desktop popover styling
+   */
+  item: 'rounded-md p-[3px] mobile:p-1',
+};