@zanichelli/albe-web-components 19.1.3 → 19.2.0

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

@@ -0,0 +1,33 @@
+import { ZColorPicker } from ".";
+import "./index";
+declare const StoryMeta: {
+    title: string;
+    component: string;
+    argTypes: {
+        lng: {
+            control: {
+                type: "inline-radio";
+            };
+            options: string[];
+        };
+        selectedColor: {
+            control: {
+                type: "select";
+                labels: {
+                    [k: string]: "Trasparente" | "Bianco" | "Grigio" | "Grigio scuro 1" | "Grigio scuro 2" | "Rosso chiaro 1" | "Rosso chiaro 2" | "Rosso" | "Rosso scuro 1" | "Rosso scuro 2" | "Arancione chiaro 1" | "Arancione chiaro 2" | "Arancione" | "Arancione scuro 1" | "Arancione scuro 2" | "Giallo chiaro 1" | "Giallo chiaro 2" | "Giallo" | "Giallo scuro 1" | "Giallo scuro 2" | "Verde chiaro 1" | "Verde chiaro 2" | "Verde" | "Verde scuro 1" | "Verde scuro 2" | "Verde acqua chiaro 1" | "Verde acqua chiaro 2" | "Verde acqua" | "Verde acqua scuro 1" | "Verde acqua scuro 2" | "Azzurro chiaro 1" | "Azzurro chiaro 2" | "Azzurro" | "Azzurro scuro 1" | "Azzurro scuro 2" | "Viola chiaro 1" | "Viola chiaro 2" | "Viola" | "Viola scuro 1" | "Viola scuro 2" | "Rosa chiaro 1" | "Rosa chiaro 2" | "Rosa" | "Rosa scuro 1" | "Rosa scuro 2";
+                };
+            };
+            options: string[];
+        };
+    };
+    args: {
+        lng: "it";
+        htmlAriaLabel: string;
+        selectedColor: any;
+        disableTransparent: false;
+    };
+};
+export default StoryMeta;
+export declare const Default: {
+    render: (args: ZColorPicker) => import("lit-html").TemplateResult<1>;
+};

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

@@ -1,14 +1,28 @@
+/**
+ * Component to render an SVG icon from the internal icon set, selected by `name`.
+ * This component automatically recognizes icons that have an indicator (e.g. `bg-color`, `font-color`, etc.), that can be filled with a custom color via the `indicatorColor` prop.
+ */
 export declare class ZIcon {
-    /** icon name */
+    /** Icon name */
     name: string;
-    /** icon height (optional) */
+    /** Icon height (optional) */
     height?: number | string;
-    /** icon width (optional) */
+    /** Icon width (optional) */
     width?: number | string;
-    /** icon id (optional) */
+    /** HTML `id` attribute (optional) */
     iconid?: string;
-    /** icon fill (optional) */
+    /** Name of the CSS color token to use for the icon fill color (e.g. `blue500`). */
     fill?: string;
+    /**
+     * Color to use to fill the icon's color indicator, if it has one.
+     * Can be any valid value for the `fill` svg attribute.
+     * If the icon passed through the `name` prop doesn't have a color indicator, this prop has no effect.
+     */
+    indicatorColor?: string;
+    /**
+     * Selects either a `<path>` or `<polygon>` element based on the format of the icon data.
+     * @param iconValue The SVG path data or polygon points from the ICONS set.
+     */
     private selectPathOrPolygon;
     render(): SVGElement;
 }

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

@@ -4,16 +4,6 @@ declare const StoryMeta: {
     title: string;
     component: string;
     argTypes: {
-        width: {
-            control: {
-                type: "text";
-            };
-        };
-        height: {
-            control: {
-                type: "text";
-            };
-        };
         fill: {
             options: string[];
             control: {
@@ -41,3 +31,26 @@ export declare const ZIconRem: {
     };
     render: (args: ZIcon) => import("lit-html").TemplateResult<1>;
 };
+export declare const ColorIndicator: {
+    argTypes: {
+        name: {
+            options: string[];
+            control: {
+                type: "select";
+            };
+        };
+        indicatorColor: {
+            control: {
+                type: "color";
+            };
+        };
+    };
+    args: {
+        name: string;
+        fill: string;
+        indicatorColor: string;
+        width: number;
+        height: number;
+    };
+    render: (args: ZIcon) => import("lit-html").TemplateResult<1>;
+};

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

@@ -35,6 +35,30 @@ export declare class ZOffcanvas {
     /** Used to skip the opening transition when the offcanvas is already open at the first render. */
     private skipAnimation;
     private canvasContainer;
+    private canvasContent;
+    private allFocusableElements;
+    private previouslyFocusedElement;
+    /**
+     * Returns all focusable elements inside the offcanvas content.
+     * Elements are considered focusable if:
+     * - They are not disabled
+     * - They are visible in the layout
+     * - They have a non-negative tabIndex or an explicit tabindex="0"
+     */
+    private getFocusableElements;
+    /**
+     * Keeps keyboard navigation trapped inside the offcanvas when it is open.
+     * Implements circular tab navigation:
+     * - If Shift + Tab is pressed on the first focusable element, move focus to the last.
+     * - If Tab is pressed on the last focusable element, move focus to the first.
+     */
+    private trapFocus;
+    /**
+     * Handles keyboard interactions when the offcanvas is open.
+     * - Closes the offcanvas when the Escape key is pressed.
+     * - Traps focus inside the component when the Tab key is used.
+     */
+    handleKeyDown(event: KeyboardEvent): void;
     /**
      * Stop the event default behavior and propagation when the offcanvas is closed.
      */

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

@@ -36,8 +36,9 @@ export declare class ZPopover {
     /** Whether to center the popup on the main side (according to "position"). */
     center: boolean;
     /**
-     * If true, the popover can be closed by clicking outside of it or pressing the escape key.
+     * Whether the popover can be closed by clicking outside of it or pressing the escape key.
      * Otherwise, it will be closed only programmatically (by setting `open` to `false`).
+     * Default: `true`.
      */
     closable: boolean;
     /**
@@ -57,9 +58,13 @@ export declare class ZPopover {
     /** Last bounding rect of the bound element to detect changes and eventually invalidate the caches. */
     private lastBoundRect?;
     /** Fired when the position changes. */
-    positionChange: EventEmitter;
-    /** Open change event. */
-    openChange: EventEmitter;
+    positionChange: EventEmitter<{
+        position: PopoverPosition;
+    }>;
+    /** Event emitted when the open state of the popover changes (e.g. when the user clicks outside the popover to close it, if `closable` is true). */
+    openChange: EventEmitter<{
+        open: boolean;
+    }>;
     closePopoverWithKeyboard(e: KeyboardEvent): void;
     /**
      * Close the popover when clicking outside of its content.

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

@@ -10,6 +10,10 @@ export declare class ZSearchbar {
     htmlid: string;
     /** Prevent submit action */
     preventSubmit?: boolean;
+    /** the input label */
+    label?: string;
+    /** the input aria-label */
+    htmlAriaLabel?: string;
     /** Input search string */
     value?: string;
     /** Search input placeholder */

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

@@ -35,6 +35,8 @@ declare const StoryMeta: {
         htmlid: string;
         placeholder: string;
         value: string;
+        label: string;
+        htmlAriaLabel: string;
         "--z-searchbar-results-height": string;
         "--z-searchbar-tag-text-color": string;
         "--z-searchbar-tag-bg": string;

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

@@ -0,0 +1,103 @@
+import { EventEmitter } from "../../stencil-public-runtime";
+import { ColorPickerPalette, PopoverPosition } from "../../beans";
+import { ZColorPickerCustomEvent, ZToolCustomEvent } from "../../components";
+import { IconName } from "../../constants/iconset";
+/**
+ * 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: 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 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;
+    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?;
+    /** 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;
+    /**
+     * 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

@@ -0,0 +1,70 @@
+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;
+    argTypes: {
+        tooltipPosition: {
+            options: PopoverPosition[];
+            control: {
+                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: {
+    render: (args: ZTool) => import("lit-html").TemplateResult<1>;
+};
+export declare const Active: {
+    args: {
+        active: true;
+    };
+    render: (args: ZTool) => import("lit-html").TemplateResult<1>;
+};
+export declare const Disabled: {
+    args: {
+        disabled: true;
+    };
+    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

@@ -0,0 +1,46 @@
+import { ZToolCustomEvent } from "../../components";
+/**
+ * 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;
+    /** Accessible label for the toolbar. */
+    htmlAriaLabel?: string;
+    /** Index of the currently focusable item (roving tabindex). */
+    currentFocusIndex: number;
+    /** List of focusable tool elements. */
+    private toolItems;
+    componentDidLoad(): void;
+    /** 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;
+    /**
+     * 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

@@ -0,0 +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;
+    args: {
+        htmlAriaLabel: string;
+    };
+    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: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
+};
+export declare const WithDividers: {
+    render: (args: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
+};
+export declare const WithNestedToolbar: {
+    render: (args: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
+};
+export declare const WithDisabledTool: {
+    render: (args: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
+};
+export declare const WithActiveTool: {
+    render: (args: ZToolbarStoriesArgs) => import("lit-html").TemplateResult<1>;
+};
+export declare const MultilineMobile: {
+    args: {
+        "--z-toolbar-columns": string;
+    };
+    parameters: {
+        viewport: {
+            defaultViewport: string;
+        };
+    };
+    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;