@zanichelli/albe-web-components 19.1.4-RC1 → 19.2.0

package/dist/types/components/z-tool/index.d.ts

@@ -1,38 +1,102 @@
 import { EventEmitter } from "../../stencil-public-runtime";
-import { PopoverPosition } from "../../beans";
+import { ColorPickerPalette, PopoverPosition } from "../../beans";
+import { ZColorPickerCustomEvent, ZToolCustomEvent } from "../../components";
+import { IconName } from "../../constants/iconset";
 /**
- * ZTool component.
- * @slot - Optional slot for nested content (e.g., a secondary z-toolbar) that appears when the tool is open/clicked.
+ * ZTool component. Can display an icon, an optional tooltip (mainly for hints about the tool's functionality), and can contain a nested `z-toolbar` as a submenu that opens on click.
+ * @slot - Optional slot for nested content (e.g., a secondary `z-toolbar`) that appears when the tool is open/clicked.
  */
 export declare class ZTool {
     hostElement: HTMLZToolElement;
     /** Tool icon */
-    icon: string;
+    icon: IconName;
     /** Text displayed inside the tooltip. */
     tooltip?: string;
     /** Preferred tooltip position. Defaults to true. */
     tooltipPosition: PopoverPosition;
     /** Accessible label for the tool trigger. Falls back to tooltip content. */
     htmlAriaLabel?: string;
-    /** Visual selected state. */
+    /** Visual active state. */
     active: boolean;
     /** Disabled state. */
     disabled: boolean;
     /** Open state. */
     open: boolean;
+    /**
+     * Color to use to fill the icon's color indicator, if it has one.
+     * Can be any valid value for the `fill` svg attribute.
+     * The value of this prop is passed down to the `z-icon` component inside the tool.
+     *
+     * If `z-color-picker` component is used inside the tool's slot, its `colorSelected` event is listened
+     * to automatically update `indicatorColor` and change the color of the icon indicator accordingly.
+     */
+    indicatorColor?: string;
     tooltipOpen: boolean;
     hasSlottedContent: boolean;
-    isNested: boolean;
+    isMobile: boolean;
+    /** Indicates if the tool has nested open tools. Used to decide whether to auto-close the submenu. */
+    hasNestedOpenTools: boolean;
     /** Emitted when the open state changes. */
     toggleSubmenu: EventEmitter;
+    /** Emitted when the tooltip open state changes. */
+    toggleTooltip: EventEmitter;
+    private buttonRef?;
     private iconRef?;
+    private tooltipRef?;
     private hoverDelay?;
-    handleOpenChange(): void;
+    /** Indicates if the tool is nested inside another tool. */
+    private isNested;
+    /** Main `z-toolbar` ancestor element, meant to be the top-level toolbar not nested inside another tool. */
+    private mainToolbar?;
+    /** Media query list for detecting mobile view. */
+    private mql?;
+    /** Listener for changes in the mobile view media query. */
+    private onMobileViewChange?;
+    /**
+     * Opens the tooltip with a delay when the button is hovered or focused, and if the tool's content isn't already visible.
+     */
     private handleTooltipOpen;
+    /**
+     * Closes the tooltip immediately on button blur or when the mouse leaves the button or the tooltip, clearing any pending hover delay.
+     */
     private handleTooltipClose;
+    /**
+     * Handles click events on the tool's button element.
+     * If the tool has slotted content, toggles the open state and focuses the active/selected item in the nested toolbar or color picker,
+     * or the first item if no active/selected item is found.
+     */
     private handleClick;
-    private focusNestedToolbar;
-    private checkIfNested;
+    /**
+     * Handles `openChange` events from the tooltip popover to keep the `tooltipOpen` state in sync, but only if the event is coming from this tool's tooltip (and not from nested tools' tooltips).
+     */
+    private onTooltipOpenChange;
+    handleOpenChange(): void;
+    handleTooltipOpenChange(): void;
+    /**
+     * Handle `ESC` and `shift+TAB` to close the submenu and move focus back to the button.
+     */
+    handleKeyDown(event: KeyboardEvent): void;
+    /**
+     * Close the popover on clicks outside the component, only if there are no nested open tools.
+     * In that case any outside click should close the nested submenu(s) first.
+     */
+    onOutsideClick(event: MouseEvent): void;
+    onNestedToolToggle(ev: ZToolCustomEvent<boolean>): void;
+    /**
+     * Handles the `colorSelected` event from a nested `z-color-picker` component.
+     * Updates the `indicatorColor` and closes the tool's popover.
+     */
+    handleColorSelected(event: ZColorPickerCustomEvent<ColorPickerPalette>): void;
+    /**
+     * Close the submenu when focus moves outside the tool.
+     */
+    handleExternalFocusin(ev: FocusEvent): void;
+    /** Focuses the tool's button element. */
+    setFocus(): Promise<void>;
+    /** Sets the tab index of the tool's internal button element. */
+    setTabIndex(value: number): Promise<void>;
+    /** Closes the tooltip. */
+    closeTooltip(): Promise<void>;
     componentWillLoad(): void;
     disconnectedCallback(): void;
     render(): HTMLZToolElement;

package/dist/types/components/z-tool/index.stories.d.ts

@@ -1,18 +1,11 @@
 import { type ZTool } from ".";
 import { PopoverPosition } from "../../beans";
+import "../z-color-picker/index";
 import "./index";
 import "./index.stories.css";
 declare const StoryMeta: {
     title: string;
     component: string;
-    args: {
-        icon: string;
-        tooltip: string;
-        tooltipPosition: PopoverPosition.TOP;
-        htmlAriaLabel: string;
-        active: false;
-        disabled: false;
-    };
     argTypes: {
         tooltipPosition: {
             options: PopoverPosition[];
@@ -20,19 +13,33 @@ declare const StoryMeta: {
                 type: "select";
             };
         };
+        indicatorColor: {
+            control: "color";
+        };
+        icon: {
+            options: string[];
+            control: {
+                type: "select";
+            };
+        };
+    };
+    args: {
+        active: false;
+        disabled: false;
+        htmlAriaLabel: string;
+        icon: "gear";
+        indicatorColor: string;
+        tooltip: string;
+        tooltipPosition: PopoverPosition.TOP;
     };
 };
 export default StoryMeta;
 export declare const Default: {
-    args: {
-        tooltipPosition: PopoverPosition.RIGHT;
-    };
     render: (args: ZTool) => import("lit-html").TemplateResult<1>;
 };
 export declare const Active: {
     args: {
         active: true;
-        tooltipPosition: PopoverPosition.RIGHT;
     };
     render: (args: ZTool) => import("lit-html").TemplateResult<1>;
 };
@@ -42,3 +49,22 @@ export declare const Disabled: {
     };
     render: (args: ZTool) => import("lit-html").TemplateResult<1>;
 };
+export declare const WithToolbar: {
+    render: (args: ZTool) => import("lit-html").TemplateResult<1>;
+};
+export declare const ColorPicker: {
+    args: {
+        icon: "bg-color";
+        indicatorColor: string;
+        tooltip: string;
+    };
+    parameters: {
+        docs: {
+            story: {
+                inline: boolean;
+                height: string;
+            };
+        };
+    };
+    render: (args: ZTool) => import("lit-html").TemplateResult<1>;
+};

package/dist/types/components/z-toolbar/index.d.ts

@@ -1,8 +1,11 @@
+import { ZToolCustomEvent } from "../../components";
 /**
- * ZToolbar component.
+ * ZToolbar component. This component mainly serves as a container for `z-tool` elements, but can also be nested inside a `z-tool` to create submenus.
  * Implements WCAG toolbar pattern with roving tabindex keyboard navigation.
  * Tools can be visually grouped using `z-divider` elements as separators.
  * @see https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/
+ *
+ * @cssprop --z-toolbar-columns - Number of items per row in the toolbar. Only applies on mobile viewport, when the toolbar can be displayed in a multi-row layout. Default: `6`.
  */
 export declare class ZToolbar {
     hostElement: HTMLZToolbarElement;
@@ -13,17 +16,31 @@ export declare class ZToolbar {
     /** List of focusable tool elements. */
     private toolItems;
     componentDidLoad(): void;
-    /** Collect all z-tool elements in the toolbar (not nested ones). */
+    /** Collect first level children `z-tool` elements in the toolbar (not nested ones). */
     private collectToolItems;
+    /**
+     * Update the `tabindex` of all children tools based on the current focus index,
+     * so that only the currently focusable tool is in the tab order (tabindex="0") and all others are not focusable via keyboard (tabindex="-1").
+     */
     private updateTabIndexes;
     private focusToolAt;
     private focusNextTool;
     private focusPreviousTool;
-    private focusParentTool;
-    /** Close all open submenus in the toolbar. */
-    closeSubmenus(): Promise<void>;
-    closeSibilingSubmenusOnOpen(event: CustomEvent): void;
+    /**
+     * Listen for custom "toggleSubmenu" events from child tools and close sibling submenus when one is opened,
+     * to prevent multiple submenus from being open at the same time.
+     */
+    closeSiblingSubmenusOnOpen(event: ZToolCustomEvent<boolean>): void;
+    /**
+     * Listen for custom "toggleTooltip" events from child tools and close sibling tooltips when one is opened,
+     * to prevent multiple tooltips from being open at the same time.
+     */
+    closeSiblingTooltipsOnOpen(event: ZToolCustomEvent<boolean>): void;
     handleKeyDown(event: KeyboardEvent): void;
+    /**
+     * When focus enters the toolbar, update the current focus index to match the focused tool,
+     * so that roving tabindex is in sync with actual focus.
+     */
     handleFocusIn(event: FocusEvent): void;
     render(): HTMLZToolbarElement;
 }

package/dist/types/components/z-toolbar/index.stories.d.ts

@@ -1,49 +1,52 @@
 import { type ZToolbar } from ".";
+import { CSSVarsArguments } from "../../utils/storybook-utils";
+import "../z-button/index";
 import "../z-divider/index";
 import "../z-tool/index";
 import "./index";
+import "./index.stories.css";
+type ZToolbarStoriesArgs = ZToolbar & CSSVarsArguments<"--z-toolbar-columns">;
+/**
+ * This component mainly serves as a container for `z-tool` elements, but can also be nested inside a `z-tool` to create submenus.
+ * ### Active state
+ * The `active` state of each `z-tool` must be managed manually by the consumer. The component does not toggle `active` on click by itself. In these stories, a click listener (decorator) is applied to toggle `active` on tools without a submenu, for demonstration purposes.
+ * ### Visual grouping with `z-divider`
+ * Use `<z-divider orientation="vertical">` between tools to visually separate them into groups. On tablet viewports and below, dividers are automatically hidden.
+ * ### Mobile multiline layout with `--z-toolbar-columns`
+ * Set the CSS custom property `--z-toolbar-columns` on a parent element to control the number of columns in the toolbar grid. When set, the toolbar switches to a grid layout on tablet viewports and below (max-width: 1151px), wrapping tools across multiple rows with a separator line between rows.
+ */
 declare const StoryMeta: {
     title: string;
     component: string;
-    parameters: {
-        docs: {
-            description: {
-                component: string;
-            };
-        };
-    };
     args: {
         htmlAriaLabel: string;
     };
-    decorators: ((story: import("@storybook/core/csf").PartialStoryFn<import("@storybook/web-components").WebComponentsRenderer, ZToolbar>) => import("lit-html").TemplateResult<1>)[];
+    decorators: ((story: import("@storybook/core/csf").PartialStoryFn<import("@storybook/web-components").WebComponentsRenderer, ZToolbarStoriesArgs>) => import("lit-html").TemplateResult<1>)[];
 };
 export default StoryMeta;
 export declare const Default: {
-    render: (args: ZToolbar) => import("lit-html").TemplateResult<1>;
+    render: (args: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
 };
 export declare const WithDividers: {
-    render: (args: ZToolbar) => import("lit-html").TemplateResult<1>;
+    render: (args: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
 };
 export declare const WithNestedToolbar: {
-    render: (args: ZToolbar) => import("lit-html").TemplateResult<1>;
-};
-export declare const ProgrammaticSubmenuClosure: {
-    render: (args: ZToolbar) => import("lit-html").TemplateResult<1>;
-};
-export declare const ProgrammaticActivation: {
-    render: (args: ZToolbar) => import("lit-html").TemplateResult<1>;
+    render: (args: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
 };
 export declare const WithDisabledTool: {
-    render: (args: ZToolbar) => import("lit-html").TemplateResult<1>;
+    render: (args: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
 };
 export declare const WithActiveTool: {
-    render: (args: ZToolbar) => import("lit-html").TemplateResult<1>;
+    render: (args: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
 };
 export declare const MultilineMobile: {
+    args: {
+        "--z-toolbar-columns": string;
+    };
     parameters: {
         viewport: {
             defaultViewport: string;
         };
     };
-    render: (args: ZToolbar) => import("lit-html").TemplateResult<1>;
+    render: (args: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
 };

package/dist/types/components/z-tooltip/index.d.ts

@@ -1,3 +1,4 @@
+import { EventEmitter } from "../../stencil-public-runtime";
 import { PopoverPosition } from "../../beans";
 /**
  * Tooltip component.
@@ -26,6 +27,13 @@ export declare class ZTooltip {
      * Otherwise, it will be closed only programmatically (by setting `open` to `false`)."
      */
     closable: boolean;
+    /**
+     * Propagation of the `openChange` event from the internal `z-popover` to allow listening to it directly on `z-tooltip`.
+     * This is necessary to keep the internal state of the `open` prop in sync when the popover is closed by user interaction instead of programmatically.
+     */
+    openChange: EventEmitter<{
+        open: boolean;
+    }>;
     private popoverEl;
     onPopoverOpenChange(): void;
     render(): HTMLZPopoverElement;