@wallarm-org/design-system 1.0.0 → 1.1.0

package/dist/components/FilterInput/FilterInputField/ChipsWithGaps.js

@@ -22,6 +22,7 @@ const ChipsWithGaps = ({ chips, hideLeadingGap, hideTrailingGap, onChipClick, on
             children: /*#__PURE__*/ jsx(FilterInputChip, {
                 chipId: chip.id,
                 attribute: chip.attribute ?? '',
+                attributeDescription: chip.attributeDescription,
                 operator: chip.operator,
                 value: chip.value,
                 error: chip.error,

package/dist/components/FilterInput/FilterInputField/FilterInputChip/FilterInputChip.d.ts

@@ -8,6 +8,9 @@ export interface FilterInputChipProps extends Omit<HTMLAttributes<HTMLDivElement
     ref?: Ref<HTMLDivElement>;
     chipId?: string;
     attribute: string;
+    /** Description shown in a dark tooltip on hover of the attribute segment. When
+     *  absent, no tooltip renders. The operator/value segments are unaffected (AS-1060). */
+    attributeDescription?: string;
     operator?: string;
     value?: string;
     error?: ChipErrorSegment;

package/dist/components/FilterInput/FilterInputField/FilterInputChip/FilterInputChip.js

@@ -1,6 +1,7 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useCallback, useRef } from "react";
 import { cn } from "../../../../utils/cn.js";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../../../Tooltip/index.js";
 import { ChipSearchInput } from "./ChipSearchInput.js";
 import { chipVariants, emptyValueHitTarget } from "./classes.js";
 import { useEditingContext } from "./context/EditingContext.js";
@@ -8,7 +9,7 @@ import { FilterInputRemoveButton } from "./FilterInputRemoveButton.js";
 import { PairSeparator } from "./PairSeparator.js";
 import { Segment } from "./Segment.js";
 import { SEGMENT_VARIANT } from "./segmentVariant.js";
-const FilterInputChip = ({ ref, chipId, attribute, operator, value, error = false, valueParts, valueSeparator, errorValueIndices, building = false, disabled = false, pair, onRemove, onSegmentClick, onPairSegmentClick, className, ...props })=>{
+const FilterInputChip = ({ ref, chipId, attribute, attributeDescription, operator, value, error = false, valueParts, valueSeparator, errorValueIndices, building = false, disabled = false, pair, onRemove, onSegmentClick, onPairSegmentClick, className, ...props })=>{
     const interactive = !disabled;
     const internalRef = useRef(null);
     const editing = useEditingContext();
@@ -50,6 +51,15 @@ const FilterInputChip = ({ ref, chipId, attribute, operator, value, error = fals
         } : {};
     const baseActiveSegment = 0 === editingSide ? activeSegment : null;
     const pairActiveSegment = 1 === editingSide ? activeSegment : null;
+    const attributeSegment = /*#__PURE__*/ jsx(Segment, {
+        variant: SEGMENT_VARIANT.attribute,
+        className: "shrink-0",
+        error: true === effectiveError || effectiveError === SEGMENT_VARIANT.attribute,
+        onClick: interactive ? (e)=>handleSegmentClick(SEGMENT_VARIANT.attribute, e) : void 0,
+        onMouseDown: interactive && building ? handleSegmentMouseDown : void 0,
+        ...segmentEditProps(SEGMENT_VARIANT.attribute),
+        children: attribute
+    });
     const setRefs = useCallback((node)=>{
         internalRef.current = node;
         if ('function' == typeof ref) ref(node);
@@ -71,15 +81,18 @@ const FilterInputChip = ({ ref, chipId, attribute, operator, value, error = fals
         },
         ...props,
         children: [
-            /*#__PURE__*/ jsx(Segment, {
-                variant: SEGMENT_VARIANT.attribute,
-                className: "shrink-0",
-                error: true === effectiveError || effectiveError === SEGMENT_VARIANT.attribute,
-                onClick: interactive ? (e)=>handleSegmentClick(SEGMENT_VARIANT.attribute, e) : void 0,
-                onMouseDown: interactive && building ? handleSegmentMouseDown : void 0,
-                ...segmentEditProps(SEGMENT_VARIANT.attribute),
-                children: attribute
-            }),
+            attributeDescription ? /*#__PURE__*/ jsxs(Tooltip, {
+                disabled: baseActiveSegment === SEGMENT_VARIANT.attribute,
+                children: [
+                    /*#__PURE__*/ jsx(TooltipTrigger, {
+                        asChild: true,
+                        children: attributeSegment
+                    }),
+                    /*#__PURE__*/ jsx(TooltipContent, {
+                        children: attributeDescription
+                    })
+                ]
+            }) : attributeSegment,
             (operator || baseActiveSegment === SEGMENT_VARIANT.operator) && /*#__PURE__*/ jsx(Segment, {
                 variant: SEGMENT_VARIANT.operator,
                 className: "shrink-0",

package/dist/components/FilterInput/FilterInputField/FilterInputChip/Segment.d.ts

@@ -1,6 +1,9 @@
-import type { FC, FocusEvent, HTMLAttributes, KeyboardEvent } from 'react';
+import type { FC, FocusEvent, HTMLAttributes, KeyboardEvent, Ref } from 'react';
 import { type SegmentVariant } from './segmentVariant';
 export type SegmentProps = HTMLAttributes<HTMLDivElement> & {
+    /** Forwarded to the segment container — lets a Tooltip/Popover trigger anchor
+     *  to it via `asChild` (attribute-segment chip tooltip, AS-1060). */
+    ref?: Ref<HTMLDivElement>;
     variant: SegmentVariant;
     children: string;
     error?: boolean;

package/dist/components/FilterInput/FilterInputField/FilterInputChip/Segment.js

@@ -7,7 +7,7 @@ import { CHAR_WIDTH_PX } from "./constants.js";
 import { MultiValueSegment } from "./MultiValueSegment.js";
 import { useSizerWidth } from "./model/useSizerWidth.js";
 import { SEGMENT_VARIANT } from "./segmentVariant.js";
-const Segment = ({ variant, children, className, error, editing, editText, onEditChange, onEditKeyDown, onEditBlur, valueParts, valueSeparator = ', ', errorValueIndices, ...props })=>{
+const Segment = ({ ref, variant, children, className, error, editing, editText, onEditChange, onEditKeyDown, onEditBlur, valueParts, valueSeparator = ', ', errorValueIndices, ...props })=>{
     const textRef = useRef(null);
     const inputRef = useRef(null);
     const sizerRef = useRef(null);
@@ -58,6 +58,7 @@ const Segment = ({ variant, children, className, error, editing, editText, onEdi
         ...props
     });
     return /*#__PURE__*/ jsx("div", {
+        ref: ref,
         className: cn(segmentContainer, className),
         "data-slot": `segment-${variant}`,
         ...isInteractive && {

package/dist/components/FilterInput/FilterInputMenu/FilterInputFieldMenu/FieldMenuPopover.d.ts

@@ -0,0 +1,21 @@
+import { type FC } from 'react';
+export interface FieldMenuPopoverProps {
+    /** Menu open AND a described field is highlighted. */
+    open: boolean;
+    /** Filter name, shown monospace, matching the menu label's casing. */
+    title: string;
+    /** Short "what it filters by" description. */
+    description: string;
+    /** Optional monospace example block (wildcards, path patterns, ranges, IDs). */
+    example?: string;
+    /** Live rect of the highlighted row the popover aligns to. */
+    getAnchorRect: () => DOMRect | null;
+    /** Highlighted id; a change pokes a reposition as the anchor swaps between rows. */
+    repositionKey: string;
+}
+/**
+ * Discovery popover for the field-selection menu: on hover or keyboard focus of a
+ * filter attribute, surfaces its title, description, and optional example (AS-1060).
+ * Fully controlled by `open` + `getAnchorRect`; no trigger, never takes focus.
+ */
+export declare const FieldMenuPopover: FC<FieldMenuPopoverProps>;

package/dist/components/FilterInput/FilterInputMenu/FilterInputFieldMenu/FieldMenuPopover.js

@@ -0,0 +1,75 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { Popover } from "@ark-ui/react";
+import { PopoverContent } from "../../../Popover/index.js";
+import { Separator } from "../../../Separator/index.js";
+import { useFloatingRecomputeOn } from "../../hooks/useFloatingRecomputeOn.js";
+const POPOVER_POSITIONING = {
+    placement: 'right-start',
+    gutter: 4,
+    flip: true,
+    overflowPadding: 8
+};
+const FieldMenuPopover = ({ open, title, description, example, getAnchorRect, repositionKey })=>{
+    useFloatingRecomputeOn(repositionKey, open);
+    useEffect(()=>{
+        if (!open) return;
+        let raf = 0;
+        const onScroll = ()=>{
+            if (raf) return;
+            raf = requestAnimationFrame(()=>{
+                raf = 0;
+                window.dispatchEvent(new Event('resize'));
+            });
+        };
+        window.addEventListener('scroll', onScroll, true);
+        return ()=>{
+            window.removeEventListener('scroll', onScroll, true);
+            if (raf) cancelAnimationFrame(raf);
+        };
+    }, [
+        open
+    ]);
+    return /*#__PURE__*/ jsx(Popover.Root, {
+        open: open,
+        positioning: {
+            ...POPOVER_POSITIONING,
+            getAnchorRect
+        },
+        autoFocus: false,
+        closeOnInteractOutside: false,
+        closeOnEscape: false,
+        modal: false,
+        lazyMount: true,
+        unmountOnExit: true,
+        children: /*#__PURE__*/ jsxs(PopoverContent, {
+            minWidth: "240px",
+            maxWidth: "340px",
+            className: "gap-6 pointer-events-none",
+            "data-testid": "field-menu-popover",
+            children: [
+                /*#__PURE__*/ jsx("p", {
+                    className: "font-mono text-sm leading-sm text-text-primary",
+                    children: title
+                }),
+                /*#__PURE__*/ jsx("p", {
+                    className: "text-xs leading-xs text-text-secondary",
+                    children: description
+                }),
+                example && /*#__PURE__*/ jsxs(Fragment, {
+                    children: [
+                        /*#__PURE__*/ jsx(Separator, {
+                            spacing: 8
+                        }),
+                        /*#__PURE__*/ jsx("pre", {
+                            className: "m-0 font-mono text-xs leading-xs text-text-secondary whitespace-pre-wrap",
+                            children: example
+                        })
+                    ]
+                })
+            ]
+        })
+    });
+};
+FieldMenuPopover.displayName = 'FieldMenuPopover';
+export { FieldMenuPopover };

package/dist/components/FilterInput/FilterInputMenu/FilterInputFieldMenu/FilterInputFieldMenu.js

@@ -1,5 +1,5 @@
-import { jsx, jsxs } from "react/jsx-runtime";
-import { useMemo } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef } from "react";
 import { cn } from "../../../../utils/cn.js";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuFooter } from "../../../DropdownMenu/index.js";
 import { Kbd } from "../../../Kbd/Kbd.js";
@@ -7,7 +7,9 @@ import { KbdGroup } from "../../../Kbd/KbdGroup.js";
 import { buildFieldMenuSections } from "../../lib/index.js";
 import { useFieldMenuNavItems } from "../hooks/useFieldMenuNavItems.js";
 import { useKeyboardNav } from "../hooks/useKeyboardNav.js";
+import { useMenuScrollHighlightSync } from "../hooks/useMenuScrollHighlightSync.js";
 import { MenuEmptyState } from "../MenuEmptyState.js";
+import { FieldMenuPopover } from "./FieldMenuPopover.js";
 import { FieldSections, OperatorsSection, RecentSection, SuggestionsSection } from "./FieldMenuSections.js";
 const FilterInputFieldMenu = ({ fields, filterText = '', onSelect, open = false, onOpenChange, recentConditions = [], suggestedFields = [], fieldGroups, onSelectAnd, onSelectOr, onEscape, positioning, inputRef, menuRef, className })=>{
     const limitedRecentConditions = useMemo(()=>recentConditions.slice(0, 3), [
@@ -38,7 +40,7 @@ const FilterInputFieldMenu = ({ fields, filterText = '', onSelect, open = false,
         } else if ('and' === data.type) onSelectAnd?.();
         else if ('or' === data.type) onSelectOr?.();
     };
-    const { highlightedValue, onHighlightChange, registerItem } = useKeyboardNav({
+    const { highlightedValue, onHighlightChange, registerItem, getItemElement } = useKeyboardNav({
         items: flatItems,
         open,
         onSelect: handleItemSelect,
@@ -49,74 +51,108 @@ const FilterInputFieldMenu = ({ fields, filterText = '', onSelect, open = false,
         menuRef
     });
     const hasResults = sections.length > 0 || !filterText;
-    return /*#__PURE__*/ jsx(DropdownMenu, {
-        open: open && hasResults,
-        onOpenChange: onOpenChange,
-        closeOnSelect: false,
-        positioning: positioning,
-        highlightedValue: highlightedValue,
-        onHighlightChange: onHighlightChange,
-        children: /*#__PURE__*/ jsxs(DropdownMenuContent, {
-            ref: menuRef,
-            className: cn('w-[300px] max-h-[430px]', className),
-            "data-slot": "filter-input-field-menu",
-            "data-filter-input-menu": "true",
-            children: [
-                !filterText && showRecent && /*#__PURE__*/ jsx(RecentSection, {
-                    conditions: limitedRecentConditions,
-                    fields: fields,
-                    onSelect: onSelect,
-                    registerItem: registerItem
-                }),
-                !filterText && showSuggestions && !showRecent && /*#__PURE__*/ jsx(SuggestionsSection, {
-                    fields: suggestedFields,
-                    onSelect: onSelect,
-                    registerItem: registerItem
-                }),
-                sections.length > 0 ? /*#__PURE__*/ jsx(FieldSections, {
-                    sections: sections,
-                    onSelect: onSelect,
-                    registerItem: registerItem
-                }) : /*#__PURE__*/ jsx(MenuEmptyState, {}),
-                !filterText && (onSelectAnd || onSelectOr) && /*#__PURE__*/ jsx(OperatorsSection, {
-                    onSelectAnd: onSelectAnd,
-                    onSelectOr: onSelectOr,
-                    registerItem: registerItem
-                }),
-                /*#__PURE__*/ jsxs(DropdownMenuFooter, {
-                    className: "justify-start",
+    const highlightedField = useMemo(()=>{
+        if (!highlightedValue) return;
+        const data = flatItems.find((i)=>i.id === highlightedValue)?.value;
+        return data?.type === 'field' ? data.field : void 0;
+    }, [
+        flatItems,
+        highlightedValue
+    ]);
+    const highlightedValueRef = useRef(highlightedValue);
+    highlightedValueRef.current = highlightedValue;
+    const getPopoverAnchorRect = useCallback(()=>{
+        const el = getItemElement(highlightedValueRef.current);
+        if (!el) return null;
+        const item = el.getBoundingClientRect();
+        const menu = el.closest('[data-filter-input-menu="true"]')?.getBoundingClientRect();
+        return menu ? new DOMRect(menu.x, item.y, menu.width, item.height) : item;
+    }, [
+        getItemElement
+    ]);
+    const popoverOpen = open && hasResults && !!highlightedField?.description;
+    const menuVisible = open && hasResults;
+    useMenuScrollHighlightSync(menuVisible, onHighlightChange);
+    return /*#__PURE__*/ jsxs(Fragment, {
+        children: [
+            /*#__PURE__*/ jsx(DropdownMenu, {
+                open: open && hasResults,
+                onOpenChange: onOpenChange,
+                closeOnSelect: false,
+                positioning: positioning,
+                highlightedValue: highlightedValue,
+                onHighlightChange: onHighlightChange,
+                children: /*#__PURE__*/ jsxs(DropdownMenuContent, {
+                    ref: menuRef,
+                    className: cn('w-[300px] max-h-[430px]', className),
+                    "data-slot": "filter-input-field-menu",
+                    "data-filter-input-menu": "true",
                     children: [
-                        /*#__PURE__*/ jsxs("span", {
-                            className: "flex items-center gap-4",
+                        !filterText && showRecent && /*#__PURE__*/ jsx(RecentSection, {
+                            conditions: limitedRecentConditions,
+                            fields: fields,
+                            onSelect: onSelect,
+                            registerItem: registerItem
+                        }),
+                        !filterText && showSuggestions && !showRecent && /*#__PURE__*/ jsx(SuggestionsSection, {
+                            fields: suggestedFields,
+                            onSelect: onSelect,
+                            registerItem: registerItem
+                        }),
+                        sections.length > 0 ? /*#__PURE__*/ jsx(FieldSections, {
+                            sections: sections,
+                            onSelect: onSelect,
+                            registerItem: registerItem
+                        }) : /*#__PURE__*/ jsx(MenuEmptyState, {}),
+                        !filterText && (onSelectAnd || onSelectOr) && /*#__PURE__*/ jsx(OperatorsSection, {
+                            onSelectAnd: onSelectAnd,
+                            onSelectOr: onSelectOr,
+                            registerItem: registerItem
+                        }),
+                        /*#__PURE__*/ jsxs(DropdownMenuFooter, {
+                            className: "justify-start",
                             children: [
-                                /*#__PURE__*/ jsxs(KbdGroup, {
+                                /*#__PURE__*/ jsxs("span", {
+                                    className: "flex items-center gap-4",
                                     children: [
-                                        /*#__PURE__*/ jsx(Kbd, {
-                                            children: "↑"
+                                        /*#__PURE__*/ jsxs(KbdGroup, {
+                                            children: [
+                                                /*#__PURE__*/ jsx(Kbd, {
+                                                    children: "↑"
+                                                }),
+                                                /*#__PURE__*/ jsx(Kbd, {
+                                                    children: "↓"
+                                                })
+                                            ]
                                         }),
-                                        /*#__PURE__*/ jsx(Kbd, {
-                                            children: "↓"
-                                        })
+                                        "to navigate"
                                     ]
                                 }),
-                                "to navigate"
-                            ]
-                        }),
-                        /*#__PURE__*/ jsxs("span", {
-                            className: "flex items-center gap-4",
-                            children: [
-                                /*#__PURE__*/ jsx(KbdGroup, {
-                                    children: /*#__PURE__*/ jsx(Kbd, {
-                                        children: "↵"
-                                    })
-                                }),
-                                "to select"
+                                /*#__PURE__*/ jsxs("span", {
+                                    className: "flex items-center gap-4",
+                                    children: [
+                                        /*#__PURE__*/ jsx(KbdGroup, {
+                                            children: /*#__PURE__*/ jsx(Kbd, {
+                                                children: "↵"
+                                            })
+                                        }),
+                                        "to select"
+                                    ]
+                                })
                             ]
                         })
                     ]
                 })
-            ]
-        })
+            }),
+            /*#__PURE__*/ jsx(FieldMenuPopover, {
+                open: popoverOpen,
+                title: highlightedField?.label ?? '',
+                description: highlightedField?.description ?? '',
+                example: highlightedField?.example,
+                getAnchorRect: getPopoverAnchorRect,
+                repositionKey: highlightedValue
+            })
+        ]
     });
 };
 FilterInputFieldMenu.displayName = 'FilterInputFieldMenu';

package/dist/components/FilterInput/FilterInputMenu/hooks/useKeyboardNav.d.ts

@@ -35,5 +35,6 @@ export declare const useKeyboardNav: ({ items, open, onSelect, onClose, onArrowR
     }) => void;
     pendingIds: Set<string>;
     registerItem: (id: string) => (el: HTMLElement | null) => void;
+    getItemElement: (id: string) => HTMLElement | null;
 };
 export {};

package/dist/components/FilterInput/FilterInputMenu/hooks/useKeyboardNav.js

@@ -7,6 +7,7 @@ const useKeyboardNav = ({ items, open, onSelect, onClose, onArrowRight, onArrowL
             if (el) itemRegistryRef.current.set(id, el);
             else itemRegistryRef.current.delete(id);
         }, []);
+    const getItemElement = useCallback((id)=>itemRegistryRef.current.get(id) ?? null, []);
     const activeIndexRef = useRef(-1);
     const pendingIdsRef = useRef(pendingIds);
     pendingIdsRef.current = pendingIds;
@@ -253,7 +254,8 @@ const useKeyboardNav = ({ items, open, onSelect, onClose, onArrowRight, onArrowL
         highlightedValue,
         onHighlightChange,
         pendingIds,
-        registerItem
+        registerItem,
+        getItemElement
     };
 };
 export { useKeyboardNav };

package/dist/components/FilterInput/FilterInputMenu/hooks/useMenuScrollHighlightSync.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Keeps the field-menu highlight — and the description popover that follows it —
+ * on the row under the cursor when the list scrolls beneath a stationary pointer
+ * (wheel/trackpad). Ark moves the highlight only on `pointermove`, so a scroll
+ * would otherwise strand it. On scroll we hit-test the last pointer and drive the
+ * highlight via `onHighlightChange` (a synthetic `pointermove` is ignored by zag
+ * when the position is unchanged). Guarded off during arrow-key nav so a resting
+ * pointer can't hijack the keyboard. Pass `enabled` for the whole time the menu
+ * is visible so the pointer is tracked before the first scroll (AS-1060).
+ */
+export declare const useMenuScrollHighlightSync: (enabled: boolean, onHighlightChange: (details: {
+    highlightedValue: string | null;
+}) => void) => void;

package/dist/components/FilterInput/FilterInputMenu/hooks/useMenuScrollHighlightSync.js

@@ -0,0 +1,46 @@
+import { useEffect, useRef } from "react";
+const useMenuScrollHighlightSync = (enabled, onHighlightChange)=>{
+    const lastPointerRef = useRef(null);
+    const keyboardNavRef = useRef(false);
+    useEffect(()=>{
+        if (!enabled) return;
+        const trackPointer = (e)=>{
+            keyboardNavRef.current = false;
+            lastPointerRef.current = {
+                x: e.clientX,
+                y: e.clientY
+            };
+        };
+        const trackKeyboard = (e)=>{
+            if ('ArrowDown' === e.key || 'ArrowUp' === e.key) keyboardNavRef.current = true;
+        };
+        let raf = 0;
+        const onScroll = ()=>{
+            if (raf || keyboardNavRef.current) return;
+            raf = requestAnimationFrame(()=>{
+                raf = 0;
+                const p = lastPointerRef.current;
+                if (!p) return;
+                const item = document.elementFromPoint(p.x, p.y)?.closest('[role="menuitem"]');
+                if (!item?.closest('[data-filter-input-menu="true"]')) return;
+                const value = item.getAttribute('data-value');
+                if (value) onHighlightChange({
+                    highlightedValue: value
+                });
+            });
+        };
+        window.addEventListener('pointermove', trackPointer, true);
+        window.addEventListener('keydown', trackKeyboard, true);
+        window.addEventListener('scroll', onScroll, true);
+        return ()=>{
+            window.removeEventListener('pointermove', trackPointer, true);
+            window.removeEventListener('keydown', trackKeyboard, true);
+            window.removeEventListener('scroll', onScroll, true);
+            if (raf) cancelAnimationFrame(raf);
+        };
+    }, [
+        enabled,
+        onHighlightChange
+    ]);
+};
+export { useMenuScrollHighlightSync };

package/dist/components/FilterInput/hooks/useFilterInputExpression/buildChips.js

@@ -36,6 +36,9 @@ const buildBaseChip = (i, condition, field)=>({
         id: chipId(i),
         variant: 'chip',
         attribute: field?.label || condition.field,
+        ...field?.description && {
+            attributeDescription: field.description
+        },
         operator: condition.operator ? getOperatorLabel(condition.operator, field?.type || DEFAULT_FIELD_TYPE) : void 0,
         ...condition.disabled && {
             disabled: true

package/dist/components/FilterInput/types.d.ts

@@ -22,6 +22,11 @@ export interface FilterInputChipData {
     id: string;
     variant: FilterInputChipVariant;
     attribute?: string;
+    /**
+     * Description shown as a dark tooltip on the chip's attribute segment; absent →
+     * no tooltip. Recall counterpart of the field-menu popover (AS-1060).
+     */
+    attributeDescription?: string;
     operator?: string;
     value?: string;
     error?: ChipErrorSegment;
@@ -106,6 +111,11 @@ export interface FieldMetadata {
     label: string;
     type: FieldType;
     description?: string;
+    /**
+     * Monospace example block shown under the description in the field-menu popover,
+     * for non-obvious value formats (wildcards, ranges, IDs). Multi-line via `\n` (AS-1060).
+     */
+    example?: string;
     operators?: FilterOperator[];
     default?: string | number | boolean;
     values?: FieldValueOption[];

package/dist/components/Heading/Heading.js

@@ -2,19 +2,19 @@ import { jsx } from "react/jsx-runtime";
 import { Slot } from "@radix-ui/react-slot";
 import { cva } from "class-variance-authority";
 import { cn } from "../../utils/cn.js";
-const headingVariants = cva('font-sans-display text-text-primary tracking-[-0.02em]', {
+const headingVariants = cva('font-sans-display text-text-primary', {
     variants: {
         size: {
-            sm: 'text-sm',
-            md: 'text-base',
-            lg: 'text-lg',
-            xl: 'text-xl',
-            '2xl': 'text-2xl',
-            '3xl': 'text-3xl',
-            '4xl': 'text-4xl',
-            '5xl': 'text-5xl',
-            '6xl': 'text-6xl',
-            '7xl': 'text-7xl'
+            sm: 'text-sm tracking-normal',
+            md: 'text-base tracking-normal',
+            lg: 'text-lg tracking-normal',
+            xl: 'text-xl tracking-xl',
+            '2xl': 'text-2xl tracking-2xl',
+            '3xl': 'text-3xl tracking-3xl',
+            '4xl': 'text-4xl tracking-4xl',
+            '5xl': 'text-5xl tracking-5xl',
+            '6xl': 'text-6xl tracking-6xl',
+            '7xl': 'text-7xl tracking-7xl'
         },
         weight: {
             light: 'font-light',

package/dist/metadata/components.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.89.0",
-  "generatedAt": "2026-08-14T11:47:35.825Z",
+  "version": "1.0.0",
+  "generatedAt": "2026-08-20T14:43:33.279Z",
   "components": [
     {
       "name": "Accordion",
@@ -17761,7 +17761,7 @@
         },
         {
           "name": "Sizes",
-          "code": "({ ...args }) => (\n  <VStack align='start'>\n    <Code {...args} size='xs'>\n      console.log('Extra small code text');\n    </Code>\n    <Code {...args} size='s'>\n      console.log('Small code text');\n    </Code>\n    <Code {...args} size='m'>\n      console.log('Medium code text');\n    </Code>\n    <Code {...args} size='l'>\n      console.log('Large code text');\n    </Code>\n  </VStack>\n)"
+          "code": "({ ...args }) => (\n  <VStack gap={24} align='start'>\n    {SIZES.map(({ size, metrics }) => (\n      <VStack key={size} gap={4} align='start'>\n        <Text size='xs' color='secondary'>\n          size=&apos;{size}&apos; · {metrics}\n        </Text>\n        <Code {...args} size={size}>\n          console.log('hello world');\n        </Code>\n      </VStack>\n    ))}\n  </VStack>\n)"
         },
         {
           "name": "Weights",
@@ -30188,6 +30188,12 @@
               "type": "string",
               "required": true
             },
+            {
+              "name": "attributeDescription",
+              "type": "string | undefined",
+              "required": false,
+              "description": "Description shown in a dark tooltip on hover of the attribute segment. When\n absent, no tooltip renders. The operator/value segments are unaffected (AS-1060)."
+            },
             {
               "name": "operator",
               "type": "string | undefined",
@@ -31619,7 +31625,7 @@
         },
         {
           "name": "Sizes",
-          "code": "({ ...args }) => (\n  <VStack align='start'>\n    <Heading {...args} size='sm'>\n      Small Heading\n    </Heading>\n    <Heading {...args} size='md'>\n      Medium Heading\n    </Heading>\n    <Heading {...args} size='lg'>\n      Large Heading\n    </Heading>\n    <Heading {...args} size='xl'>\n      Extra Large Heading\n    </Heading>\n    <Heading {...args} size='2xl'>\n      2XL Heading\n    </Heading>\n    <Heading {...args} size='3xl'>\n      3XL Heading\n    </Heading>\n    <Heading {...args} size='4xl'>\n      4XL Heading\n    </Heading>\n    <Heading {...args} size='5xl'>\n      5XL Heading\n    </Heading>\n    <Heading {...args} size='6xl'>\n      6XL Heading\n    </Heading>\n    <Heading {...args} size='7xl'>\n      7XL Heading\n    </Heading>\n  </VStack>\n)"
+          "code": "({ ...args }) => (\n  <VStack gap={24} align='start'>\n    {SIZES.map(({ size, metrics }) => (\n      <VStack key={size} gap={4} align='start'>\n        <Text size='xs' color='secondary'>\n          size=&apos;{size}&apos; · {metrics}\n        </Text>\n        <Heading {...args} size={size}>\n          The quick brown fox\n        </Heading>\n      </VStack>\n    ))}\n  </VStack>\n)"
         },
         {
           "name": "Weights",
@@ -79101,7 +79107,7 @@
         },
         {
           "name": "Sizes",
-          "code": "({ ...args }) => (\n  <VStack align='start'>\n    <Text {...args} size='xs'>\n      Extra Small Body Text\n    </Text>\n    <Text {...args} size='sm'>\n      Small Body Text\n    </Text>\n    <Text {...args} size='md'>\n      Medium Body Text\n    </Text>\n    <Text {...args} size='lg'>\n      Large Body Text\n    </Text>\n    <Text {...args} size='xl'>\n      Extra Large Body Text\n    </Text>\n  </VStack>\n)"
+          "code": "({ ...args }) => (\n  <VStack gap={24} align='start'>\n    {SIZES.map(({ size, metrics }) => (\n      <VStack key={size} gap={4} align='start'>\n        <Text size='xs' color='secondary'>\n          size=&apos;{size}&apos; · {metrics}\n        </Text>\n        <Text {...args} size={size}>\n          The quick brown fox jumps over the lazy dog\n        </Text>\n      </VStack>\n    ))}\n  </VStack>\n)"
         },
         {
           "name": "Weights",
@@ -89983,6 +89989,34 @@
         {
           "name": "--leading-9xl",
           "value": "128px"
+        },
+        {
+          "name": "--tracking-xl",
+          "value": "-0.005em"
+        },
+        {
+          "name": "--tracking-2xl",
+          "value": "-0.01em"
+        },
+        {
+          "name": "--tracking-3xl",
+          "value": "-0.01em"
+        },
+        {
+          "name": "--tracking-4xl",
+          "value": "-0.015em"
+        },
+        {
+          "name": "--tracking-5xl",
+          "value": "-0.015em"
+        },
+        {
+          "name": "--tracking-6xl",
+          "value": "-0.02em"
+        },
+        {
+          "name": "--tracking-7xl",
+          "value": "-0.02em"
         }
       ]
     },

package/dist/theme/Pixel.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryFn } from 'storybook-react-rsbuild';
+import { HStack, VStack } from '../components/Stack';
+import { Text } from '../components/Text';
+
+const DESCRIPTION = [
+  'Geist Pixel is the decorative typeface. Use it for empty states, and for moments that want personality rather than information.',
+  'There is no `Pixel` component. Pixel type is composed from the `font-pixel` utility plus the shared `text-*` size utilities, so the steps below are conventions rather than a component API. The only place it ships today is `EmptyStateTitle`, at 16/24.',
+  'One cut only: Square at regular weight. There is no light or bold, so `font-bold` on pixel type renders as a browser-synthesized fake — emphasis has to come from size or colour, never from weight.',
+  'Not for UI copy, labels, or anything read at length; that is the text ramp. Keep it to short strings, where the blocky letterforms stay legible.',
+].join('\n\n');
+
+const meta = {
+  title: 'Typography/Pixel',
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: DESCRIPTION,
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+
+type PixelStep = {
+  /** Name of the matching text style in Figma. */
+  token: string;
+  /** Utilities that reproduce it — note lg is 16px, so it maps to text-base. */
+  utilities: string;
+  /** Size / leading in px. */
+  metrics: string;
+};
+
+const STEPS: PixelStep[] = [
+  { token: 'pixel-3xl', utilities: 'font-pixel text-3xl', metrics: '30 / 36' },
+  { token: 'pixel-2xl', utilities: 'font-pixel text-2xl', metrics: '24 / 32' },
+  { token: 'pixel-xl', utilities: 'font-pixel text-xl', metrics: '20 / 28' },
+  { token: 'pixel-lg', utilities: 'font-pixel text-base', metrics: '16 / 24' },
+];
+
+export const Scale: StoryFn<typeof meta> = () => (
+  <VStack gap={32} align='start'>
+    {STEPS.map(({ token, utilities, metrics }) => (
+      <VStack key={token} gap={8} align='start'>
+        <HStack gap={12} align='baseline'>
+          <Text size='sm' weight='medium'>
+            {token}
+          </Text>
+          <Text size='xs' color='secondary'>
+            {metrics} · {utilities}
+          </Text>
+        </HStack>
+        <span className={`${utilities} text-text-primary`}>The quick brown fox</span>
+      </VStack>
+    ))}
+  </VStack>
+);
+
+export const Decorative: StoryFn<typeof meta> = () => (
+  <VStack gap={40} align='start'>
+    <VStack gap={12} align='start'>
+      <Text size='xs' color='secondary'>
+        What it is for — a short, decorative line carrying the personality
+      </Text>
+      <span className='font-pixel text-base text-text-primary'>No attacks detected</span>
+    </VStack>
+
+    <VStack gap={12} align='start'>
+      <Text size='xs' color='secondary'>
+        What it is not for — running copy belongs to the text ramp
+      </Text>
+      <Text size='sm' color='secondary' className='max-w-100'>
+        Wallarm did not find any attacks in the selected period. Try widening the time range, or
+        check that the filters above are not excluding traffic you expect to see.
+      </Text>
+    </VStack>
+  </VStack>
+);

package/dist/theme/typography.css

@@ -79,4 +79,17 @@
     --leading-7xl: 72px;
     --leading-8xl: 96px;
     --leading-9xl: 128px;
+
+    /* Optical tracking for the heading ramp. Tightens as the size grows, because
+       large type sets too loose at the spacing Geist is drawn for.
+       Zero below 20px system-wide: at UI sizes the font's own spacing is already
+       right, and negative tracking there costs legibility. Steps sm/md/lg get no
+       token on purpose — they use tracking-normal. */
+    --tracking-xl: -0.005em;
+    --tracking-2xl: -0.01em;
+    --tracking-3xl: -0.01em;
+    --tracking-4xl: -0.015em;
+    --tracking-5xl: -0.015em;
+    --tracking-6xl: -0.02em;
+    --tracking-7xl: -0.02em;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wallarm-org/design-system",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Core design system library with React components and Storybook documentation",
   "publishConfig": {
     "access": "public",