@taiv/ui 1.15.0 → 2.0.0

package/dist/components/Misc/OverflowFade/OverflowFade.stories.js

@@ -0,0 +1,112 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { neutral, primary } from '../../../constants/colors';
+import { spacing } from '../../../constants/spacing';
+import { Badge } from '../../Info/Badge/Badge';
+import { Group } from '../../Layout/Group/Group';
+import { Stack } from '../../Layout/Stack/Stack';
+import { Text } from '../../Typography/Text/Text';
+import { OverflowFade } from './OverflowFade';
+const meta = {
+    argTypes: {
+        background: {
+            control: { type: 'color' },
+            description: 'Color the gradient fades into. Match the surrounding surface.',
+            table: { defaultValue: { summary: "'white'" } },
+        },
+        fadeWidth: {
+            control: { type: 'number' },
+            table: { defaultValue: { summary: '40' } },
+        },
+    },
+    component: OverflowFade,
+    parameters: {
+        docs: {
+            description: {
+                component: 'Bidirectional gradient fades for horizontal or vertical overflow. Horizontal (default): left/right fades ' +
+                    'on `overflow-x` scroll. Vertical (`orientation="vertical"`): top/bottom fades — pass `maxHeight` so ' +
+                    'the viewport clips. Fades auto-hide when content fits.\n\n' +
+                    'The scrollbar is hidden by design — the gradient is the affordance.',
+            },
+        },
+        layout: 'padded',
+    },
+    title: 'Components/Misc/OverflowFade',
+};
+export default meta;
+const chips = [
+    'All',
+    'Trending',
+    'Recently Added',
+    'Most Played',
+    'Editor Picks',
+    'Sports',
+    'News',
+    'Holiday',
+    'Promotions',
+    'Announcements',
+    'Weather',
+];
+const Chip = ({ label, active }) => (_jsx("div", { style: {
+        background: active ? primary[200] : 'white',
+        border: `1px solid ${active ? primary[200] : neutral[100]}`,
+        borderRadius: 999,
+        color: active ? 'white' : neutral[300],
+        flexShrink: 0,
+        fontSize: 14,
+        padding: `${spacing.xs} ${spacing.md}`,
+        whiteSpace: 'nowrap',
+    }, children: label }));
+export const Default = {
+    args: {
+        background: 'white',
+        fadeWidth: 40,
+    },
+    render: (args) => (_jsx("div", { style: { background: 'white', maxWidth: 480, padding: spacing.md }, children: _jsxs(Stack, { gap: spacing.sm, children: [_jsx(Text, { variant: 'label', children: "Resize the panel narrower to see the right-edge fade appear." }), _jsx(OverflowFade, { ...args, children: _jsx(Group, { gap: spacing.xs, noWrap: true, children: chips.map((label) => (_jsx(Chip, { label: label }, label))) }) })] }) })),
+};
+export const NoOverflow = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'When content fits the container, neither fade renders — auto-detection via scrollWidth/clientWidth.',
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { background: 'white', maxWidth: 480, padding: spacing.md }, children: _jsx(OverflowFade, { children: _jsxs(Group, { gap: spacing.xs, noWrap: true, children: [_jsx(Chip, { active: true, label: 'All' }), _jsx(Chip, { label: 'Sports' }), _jsx(Chip, { label: 'News' })] }) }) })),
+};
+export const OnNonWhiteSurface = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'Pass `background` to match a non-white surface so the gradient ends in the parent color, not white.',
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { background: neutral[25], maxWidth: 480, padding: spacing.md }, children: _jsxs(Stack, { gap: spacing.sm, children: [_jsx(Text, { variant: 'label', children: "On neutral[25] \u2014 fade matches surface." }), _jsx(OverflowFade, { background: neutral[25], children: _jsx(Group, { gap: spacing.xs, noWrap: true, children: chips.map((label, i) => (_jsx(Chip, { active: i === 0, label: label }, label))) }) })] }) })),
+};
+export const Vertical = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'Vertical scroll with top/bottom fades. Requires `maxHeight` on the viewport so content can overflow.',
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { background: 'white', maxWidth: 360, padding: spacing.md }, children: _jsx(OverflowFade, { fadeWidth: 48, maxHeight: 220, orientation: 'vertical', children: _jsx(Stack, { gap: spacing.sm, children: Array.from({ length: 14 }, (_, i) => (_jsxs(Text, { variant: 'body', children: ["Row ", i + 1, " \u2014 scroll to see top and bottom edge fades."] }, i))) }) }) })),
+};
+export const WithBadges = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'Demonstrates use with richer children — a tab-strip-like row with counts.',
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { background: 'white', maxWidth: 520, padding: spacing.md }, children: _jsx(OverflowFade, { children: _jsx(Group, { gap: spacing.lg, noWrap: true, children: [
+                    'Your Slides',
+                    'Smart Content',
+                    'Premades',
+                    'Playlists',
+                    'Drafts',
+                    'Archived',
+                ].map((label, i) => (_jsxs(Group, { gap: spacing.xs, noWrap: true, style: { flexShrink: 0 }, children: [_jsx(Text, { style: { color: i === 0 ? primary[200] : neutral[300] }, variant: 'body', children: label }), _jsx(Badge, { color: 'neutral', size: 'sm', variant: 'filled', children: [12, 4, 8, 31, 2, 17][i] })] }, label))) }) }) })),
+};

package/dist/components/Misc/Picker/Picker.d.ts

@@ -0,0 +1,62 @@
+import { type ReactNode } from 'react';
+export interface PickerItem {
+    id: string;
+    label: string;
+    /** Right-aligned secondary info (e.g. "5 slides"). */
+    meta?: ReactNode;
+    /**
+     * Optional sortable timestamp for automatic recency. Larger = more recent.
+     * Items without `recencyKey` sort to the end of the recent view.
+     */
+    recencyKey?: number;
+    /** When true, item renders disabled (greyed-out) and is not clickable. */
+    disabled?: boolean;
+    /** Tooltip text shown on hover when disabled. */
+    disabledReason?: string;
+}
+export type PickerPosition = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end';
+export interface PickerProps {
+    items: PickerItem[];
+    /**
+     * How many recent items to show in the compact (idle) view. If `items`
+     * has ≤ this many entries, all are shown and the "Show all" toggle is
+     * hidden. Default: 3.
+     */
+    recentCount?: number;
+    onSelect: (item: PickerItem) => void;
+    searchPlaceholder?: string;
+    /** Shown when items is empty or search has no matches. */
+    emptyMessage?: string;
+    /** Slot rendered below the list — typically a "+ Create new" button. */
+    footer?: ReactNode;
+    /**
+     * Controlled-open mode. When provided, parent owns open state — useful for
+     * triggering programmatically from outside the Target (e.g. from a kebab
+     * Menu.Item that closes its own Menu before opening the Picker).
+     */
+    opened?: boolean;
+    onOpenChange?: (opened: boolean) => void;
+    position?: PickerPosition;
+    width?: number;
+    /** Wrap dropdown in a portal to escape stacking contexts. Default true. */
+    withinPortal?: boolean;
+    /**
+     * When true, the SearchBar is hidden on mobile viewports (≤640px). Useful
+     * for kebab-anchored Pickers where search adds noise on small screens but
+     * stays valuable on desktop. Default: false.
+     */
+    searchOnDesktopOnly?: boolean;
+    /**
+     * When true, never render the "Recent" header or "Show all N" toggle —
+     * always show exactly `recentCount` items in the idle view. Search across
+     * the full list still works when the user types. Default: false.
+     */
+    disableShowAll?: boolean;
+    children: ReactNode;
+}
+export declare const Picker: (({ items, recentCount, onSelect, searchPlaceholder, emptyMessage, footer, opened, onOpenChange, position, width, withinPortal, searchOnDesktopOnly, disableShowAll, children, }: PickerProps) => import("react/jsx-runtime").JSX.Element) & {
+    Target: import("react").ForwardRefExoticComponent<{
+        children: ReactNode;
+    } & import("react").RefAttributes<HTMLDivElement>>;
+};
+//# sourceMappingURL=Picker.d.ts.map

package/dist/components/Misc/Picker/Picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Picker.d.ts","sourceRoot":"","sources":["../../../../src/components/Misc/Picker/Picker.tsx"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,SAAS,EAIf,MAAM,OAAO,CAAC;AAwBf,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,cAAc,GACtB,KAAK,GACL,WAAW,GACX,SAAS,GACT,QAAQ,GACR,cAAc,GACd,YAAY,GACZ,MAAM,GACN,YAAY,GACZ,UAAU,GACV,OAAO,GACP,aAAa,GACb,WAAW,CAAC;AAEhB,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAmQD,eAAO,MAAM,MAAM,oLAxLhB,WAAW;;kBAtB8C,SAAS;;CA8MS,CAAC"}

package/dist/components/Misc/Picker/Picker.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Box, Popover, Portal, UnstyledButton } from '@mantine/core';
+import { forwardRef, useEffect, useMemo, useState, } from 'react';
+import { neutral, primary, white } from '../../../constants/colors';
+import { fontBase } from '../../../constants/font';
+import { spacing } from '../../../constants/spacing';
+import { useMobile } from '../../../hooks/useMediaQuery';
+import { Tooltip } from '../../Info/Tooltips/Tooltip/Tooltip';
+import { SearchBar } from '../../Inputs/TextInputs/SearchBar/SearchBar';
+import { Stack } from '../../Layout/Stack/Stack';
+import { Text } from '../../Typography/Text/Text';
+const PickerItemRow = ({ item, onSelect }) => {
+    // Use Text for the label so it inherits Poppins via fontBase rather than
+    // relying on the host button to push fontFamily down. fontBase is still
+    // applied to the button itself for browsers that style buttons with the
+    // default UI font (Mantine UnstyledButton sets fontFamily: inherit, but
+    // belt-and-suspenders).
+    const button = (_jsxs(UnstyledButton, { disabled: item.disabled, onClick: item.disabled ? undefined : onSelect, sx: {
+            ...fontBase,
+            '&:hover': item.disabled ? {} : { backgroundColor: neutral[25] },
+            alignItems: 'center',
+            color: item.disabled ? neutral[100] : neutral[300],
+            cursor: item.disabled ? 'not-allowed' : 'pointer',
+            display: 'flex',
+            gap: spacing.sm,
+            justifyContent: 'space-between',
+            padding: `${spacing.sm} ${spacing.md}`,
+            transition: 'background-color 120ms ease',
+            width: '100%',
+        }, children: [_jsx(Text, { style: {
+                    color: item.disabled ? neutral[100] : neutral[300],
+                    minWidth: 0,
+                }, truncate: true, variant: 'body', children: item.label }), item.meta && (_jsx("span", { style: { color: neutral[200], flexShrink: 0 }, children: item.meta }))] }));
+    if (item.disabled && item.disabledReason) {
+        return _jsx(Tooltip, { text: item.disabledReason, children: button });
+    }
+    return button;
+};
+const PickerTarget = forwardRef(({ children }, ref) => (_jsx(Popover.Target, { ref: ref, children: children })));
+PickerTarget.displayName = 'Picker.Target';
+const PickerComponent = ({ items, recentCount = 3, onSelect, searchPlaceholder = 'Search…', emptyMessage = 'No items', footer, opened, onOpenChange, position = 'bottom-end', width = 280, withinPortal = true, searchOnDesktopOnly = false, disableShowAll = false, children, }) => {
+    const [internalOpen, setInternalOpen] = useState(false);
+    const isControlled = opened !== undefined;
+    const isOpen = isControlled ? opened : internalOpen;
+    const setOpen = (next) => {
+        if (!isControlled)
+            setInternalOpen(next);
+        onOpenChange === null || onOpenChange === void 0 ? void 0 : onOpenChange(next);
+    };
+    const isMobile = useMobile();
+    const showSearch = !searchOnDesktopOnly || !isMobile;
+    const [query, setQuery] = useState('');
+    const [showAll, setShowAll] = useState(false);
+    // Reset transient view state every time the popover closes so it opens
+    // fresh next time (no stale search query / "show all" stuck on).
+    useEffect(() => {
+        if (!isOpen) {
+            setQuery('');
+            setShowAll(false);
+        }
+    }, [isOpen]);
+    const sortedByRecency = useMemo(() => [...items].sort((a, b) => { var _a, _b; return ((_a = b.recencyKey) !== null && _a !== void 0 ? _a : 0) - ((_b = a.recencyKey) !== null && _b !== void 0 ? _b : 0); }), [items]);
+    const filtered = useMemo(() => {
+        const q = query.trim().toLowerCase();
+        if (!q)
+            return sortedByRecency;
+        return sortedByRecency.filter((i) => i.label.toLowerCase().includes(q));
+    }, [sortedByRecency, query]);
+    const isSearching = query.trim().length > 0;
+    // Compact dropdowns (e.g. card kebabs) opt out of the "Recent" header and
+    // "Show all N" toggle — they always show only `recentCount` in idle view.
+    const showShowAllToggle = !disableShowAll && !isSearching && !showAll && items.length > recentCount;
+    const showRecentHeader = showShowAllToggle;
+    const visibleItems = useMemo(() => {
+        if (isSearching)
+            return filtered;
+        if (disableShowAll)
+            return sortedByRecency.slice(0, recentCount);
+        if (showAll || items.length <= recentCount)
+            return sortedByRecency;
+        return sortedByRecency.slice(0, recentCount);
+    }, [
+        isSearching,
+        filtered,
+        showAll,
+        items.length,
+        recentCount,
+        sortedByRecency,
+        disableShowAll,
+    ]);
+    return (_jsxs(_Fragment, { children: [isOpen && (_jsx(Portal, { children: _jsx("div", { onClick: () => setOpen(false), style: { inset: 0, position: 'fixed', zIndex: 299 } }) })), _jsxs(Popover, { offset: 8, onChange: setOpen, opened: isOpen, position: position, radius: 8, shadow: 'md', styles: {
+                    dropdown: {
+                        backgroundColor: white,
+                        border: `1px solid ${neutral[50]}`,
+                        padding: 0,
+                    },
+                }, width: width, withinPortal: withinPortal, children: [children, _jsx(Popover.Dropdown, { children: _jsxs(Stack, { spacing: 0, children: [showSearch && (_jsx(Box, { p: spacing.xs, style: { borderBottom: `1px solid ${neutral[50]}` }, children: _jsx(SearchBar, { fullWidth: true, onChange: (e) => setQuery(e.target.value), placeholder: searchPlaceholder, size: 'sm', value: query }) })), showRecentHeader && (_jsx(Box, { pb: spacing.xs, pt: spacing.sm, px: spacing.md, style: { ...fontBase }, children: _jsx(Text, { style: { color: neutral[200] }, variant: 'label', children: "Recent" }) })), _jsx(Box, { style: { maxHeight: 280, overflowY: 'auto' }, children: visibleItems.length === 0 ? (_jsx(Box, { p: spacing.md, style: { textAlign: 'center' }, children: _jsx(Text, { variant: 'subtle', children: emptyMessage }) })) : (visibleItems.map((item) => (_jsx(PickerItemRow, { item: item, onSelect: () => {
+                                            onSelect(item);
+                                            setOpen(false);
+                                        } }, item.id)))) }), showShowAllToggle && (_jsx(Box, { p: spacing.xs, style: { borderTop: `1px solid ${neutral[50]}` }, children: _jsx(UnstyledButton, { onClick: () => setShowAll(true), sx: {
+                                            ...fontBase,
+                                            '&:hover': { color: primary[200] },
+                                            color: primary[200],
+                                            cursor: 'pointer',
+                                            display: 'block',
+                                            padding: `${spacing.xs} ${spacing.sm}`,
+                                            textAlign: 'center',
+                                            width: '100%',
+                                        }, children: _jsxs(Text, { style: { color: 'inherit', textAlign: 'center' }, variant: 'label', children: ["Show all ", items.length] }) }) })), footer && (_jsx(Box, { p: spacing.xs, style: { borderTop: `1px solid ${neutral[50]}` }, children: footer }))] }) })] })] }));
+};
+export const Picker = Object.assign(PickerComponent, { Target: PickerTarget });

package/dist/components/Misc/Picker/Picker.stories.d.ts

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Picker } from './Picker';
+declare const meta: Meta<typeof Picker>;
+export default meta;
+type Story = StoryObj<typeof Picker>;
+export declare const Default: Story;
+export declare const WithRecentAndShowAll: Story;
+export declare const WithFooter: Story;
+export declare const Empty: Story;
+export declare const WithDisabledItems: Story;
+export declare const Controlled: Story;
+export declare const AnchoredToIconButton: Story;
+export declare const OnDarkSurface: Story;
+//# sourceMappingURL=Picker.stories.d.ts.map

package/dist/components/Misc/Picker/Picker.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Picker.stories.d.ts","sourceRoot":"","sources":["../../../../src/components/Misc/Picker/Picker.stories.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AASlC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,OAAO,MAAM,CA4B7B,CAAC;AAEF,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,MAAM,CAAC,CAAC;AAmBrC,eAAO,MAAM,OAAO,EAAE,KAqBrB,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KA6BlC,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,KA+BxB,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KA6BnB,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,KA+B/B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,KA4BxB,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KAqBlC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,KA0C3B,CAAC"}

package/dist/components/Misc/Picker/Picker.stories.js

@@ -0,0 +1,154 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { IconPlus } from '@tabler/icons-react';
+import { Picker } from './Picker';
+import { Button } from '../../Inputs/Buttons/Button/Button';
+import { IconButton } from '../../Inputs/Buttons/IconButton/IconButton';
+import { Group } from '../../Layout/Group/Group';
+import { Stack } from '../../Layout/Stack/Stack';
+import { Text } from '../../Typography/Text/Text';
+import { spacing } from '../../../constants/spacing';
+const meta = {
+    title: 'Components/Misc/Picker',
+    component: Picker,
+    parameters: {
+        layout: 'centered',
+        docs: {
+            description: {
+                component: 'A searchable list popover for picking a single item. Idle state ' +
+                    'surfaces the most recent N items + a "Show all" toggle; typing in ' +
+                    'the search filters across the full list. Use for "add to playlist", ' +
+                    '"move to folder", or any compact pick-one flow.\n\n' +
+                    'Compose via `Picker.Target` for the trigger; the dropdown is owned ' +
+                    'by the component. For nested triggers (e.g. inside another Menu), ' +
+                    'use the controlled `opened` prop.',
+            },
+        },
+    },
+    argTypes: {
+        recentCount: {
+            control: { type: 'number' },
+            table: { defaultValue: { summary: '3' } },
+        },
+        width: {
+            control: { type: 'number' },
+            table: { defaultValue: { summary: '280' } },
+        },
+    },
+};
+export default meta;
+const fewPlaylists = [
+    { id: 'p1', label: 'Morning Mix', meta: '12 slides', recencyKey: Date.now() },
+    { id: 'p2', label: 'Lunch Specials', meta: '4 slides', recencyKey: Date.now() - 1000 },
+    { id: 'p3', label: 'Evening Wind-down', meta: '7 slides', recencyKey: Date.now() - 2000 },
+];
+const manyPlaylists = [
+    { id: 'p1', label: 'Morning Mix', meta: '12 slides', recencyKey: 9 },
+    { id: 'p2', label: 'Lunch Specials', meta: '4 slides', recencyKey: 8 },
+    { id: 'p3', label: 'Evening Wind-down', meta: '7 slides', recencyKey: 7 },
+    { id: 'p4', label: 'Trivia Night', meta: '20 slides', recencyKey: 6 },
+    { id: 'p5', label: 'Weekend Brunch', meta: '8 slides', recencyKey: 5 },
+    { id: 'p6', label: 'Holidays — December', meta: '15 slides', recencyKey: 4 },
+    { id: 'p7', label: 'Local Sports', meta: '10 slides', recencyKey: 3 },
+    { id: 'p8', label: 'Promotions', meta: '6 slides', recencyKey: 2 },
+];
+export const Default = {
+    render: () => {
+        const [picked, setPicked] = useState(null);
+        return (_jsxs(Stack, { gap: spacing.sm, align: 'center', children: [_jsx(Picker, { items: fewPlaylists, onSelect: (item) => setPicked(item.label), searchPlaceholder: 'Search playlists\u2026', emptyMessage: 'No playlists yet', children: _jsx(Picker.Target, { children: _jsx(Button, { children: "Add to playlist" }) }) }), picked && (_jsxs(Text, { variant: 'subtle', children: ["You picked: ", picked] }))] }));
+    },
+};
+export const WithRecentAndShowAll = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'When `items.length > recentCount`, the idle view shows only the top N (sorted by `recencyKey` desc) with a "Show all N" toggle. Typing in search jumps to filtered full list.',
+            },
+        },
+    },
+    render: () => {
+        const [picked, setPicked] = useState(null);
+        return (_jsxs(Stack, { gap: spacing.sm, align: 'center', children: [_jsx(Picker, { items: manyPlaylists, recentCount: 3, onSelect: (item) => setPicked(item.label), searchPlaceholder: 'Search 8 playlists\u2026', children: _jsx(Picker.Target, { children: _jsx(Button, { children: "Pick one of 8" }) }) }), picked && (_jsxs(Text, { variant: 'subtle', children: ["You picked: ", picked] }))] }));
+    },
+};
+export const WithFooter = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'A common pattern: a "+ Create new …" button below the list. The footer slot is always visible regardless of search state.',
+            },
+        },
+    },
+    render: () => (_jsx(Picker, { items: manyPlaylists, recentCount: 3, onSelect: () => undefined, searchPlaceholder: 'Search playlists\u2026', footer: _jsx(Button, { variant: 'text', size: 'sm', leftIcon: _jsx(IconPlus, { size: 14 }), fullWidth: true, children: "Create new playlist" }), children: _jsx(Picker.Target, { children: _jsx(Button, { children: "Add to playlist" }) }) })),
+};
+export const Empty = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'Empty state shows the configured message when no items exist.',
+            },
+        },
+    },
+    render: () => (_jsx(Picker, { items: [], onSelect: () => undefined, emptyMessage: 'No playlists yet', footer: _jsx(Button, { variant: 'text', size: 'sm', leftIcon: _jsx(IconPlus, { size: 14 }), fullWidth: true, children: "Create your first playlist" }), children: _jsx(Picker.Target, { children: _jsx(Button, { children: "Add to playlist" }) }) })),
+};
+export const WithDisabledItems = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'Items can be disabled with an explanatory tooltip — useful for ' +
+                    '"already in playlist" or permission-gated entries.',
+            },
+        },
+    },
+    render: () => (_jsx(Picker, { items: [
+            { id: 'p1', label: 'Morning Mix', meta: '12 slides', recencyKey: 3 },
+            {
+                id: 'p2',
+                label: 'Lunch Specials',
+                meta: 'Already in this playlist',
+                recencyKey: 2,
+                disabled: true,
+                disabledReason: 'This slide is already in "Lunch Specials".',
+            },
+            { id: 'p3', label: 'Evening Wind-down', meta: '7 slides', recencyKey: 1 },
+        ], onSelect: () => undefined, children: _jsx(Picker.Target, { children: _jsx(Button, { children: "Add to playlist" }) }) })),
+};
+export const Controlled = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'Controlled-open mode for triggering programmatically — e.g. when ' +
+                    'the trigger lives in another popover that needs to close first.',
+            },
+        },
+    },
+    render: () => {
+        const [open, setOpen] = useState(false);
+        return (_jsxs(Group, { gap: spacing.sm, align: 'center', children: [_jsx(Button, { onClick: () => setOpen(true), children: "Open Picker" }), _jsx(Picker, { items: fewPlaylists, onSelect: () => setOpen(false), opened: open, onOpenChange: setOpen, children: _jsx(Picker.Target, { children: _jsx("span", { style: { display: 'inline-block', width: 1, height: 1 } }) }) })] }));
+    },
+};
+export const AnchoredToIconButton = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'Mounting on an IconButton trigger — common in card kebabs.',
+            },
+        },
+    },
+    render: () => (_jsx(Picker, { items: fewPlaylists, onSelect: () => undefined, position: 'bottom-end', children: _jsx(Picker.Target, { children: _jsx(IconButton, { "aria-label": 'Add to playlist', variant: 'secondary', subtle: true, children: _jsx(IconPlus, { size: 16 }) }) }) })),
+};
+export const OnDarkSurface = {
+    parameters: {
+        docs: {
+            description: {
+                story: 'Picker dropdown stays light/neutral against a dark anchor surface ' +
+                    '(e.g. when triggered from a dark selection toolbar).',
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: {
+            background: '#1a1a22',
+            borderRadius: 12,
+            padding: spacing.md,
+        }, children: _jsx(Picker, { items: manyPlaylists, recentCount: 3, onSelect: () => undefined, position: 'top-end', footer: _jsx(Button, { variant: 'text', size: 'sm', leftIcon: _jsx(IconPlus, { size: 14 }), fullWidth: true, children: "Create new playlist" }), children: _jsx(Picker.Target, { children: _jsx(Button, { variant: 'ghost', size: 'sm', children: "Add to playlist" }) }) }) })),
+};

package/dist/components/Misc/SelectableObject/SelectableObject.d.ts

@@ -0,0 +1,38 @@
+import type React from 'react';
+export type SelectableObjectHandle = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export interface SelectableObjectProps {
+    children: React.ReactNode;
+    /** Render the selection chrome (border + handles). Default `true`. */
+    selected?: boolean;
+    /** Render the 4 corner handles when selected. Default `true`. */
+    showHandles?: boolean;
+    /** Animated marching-ants border when selected. Default `true`. */
+    animated?: boolean;
+    /** Border color. Default `primary[200]`. */
+    color?: string;
+    /**
+     * Cursor used on the wrapper. Default `'move'` when selected, otherwise
+     * `'pointer'`.
+     */
+    cursor?: React.CSSProperties['cursor'];
+    /**
+     * Fires for a click anywhere inside the object. Consumers use this to
+     * promote the object to the selected state.
+     */
+    onSelect?: (event: React.MouseEvent) => void;
+    /**
+     * Fires when a corner handle is pressed. Consumers implement the actual
+     * resize math on top of this.
+     */
+    onHandlePointerDown?: (handle: SelectableObjectHandle, event: React.PointerEvent) => void;
+    style?: React.CSSProperties;
+    className?: string;
+}
+/**
+ * Chrome wrapper that renders an animated dashed selection border and four
+ * corner resize handles around arbitrary content. Purely presentational —
+ * drag + resize math lives in the consumer. SVG rather than CSS `dashed`
+ * borders because dash offsets are not animatable on standard borders.
+ */
+export declare const SelectableObject: ({ children, selected, showHandles, animated, color, cursor, onSelect, onHandlePointerDown, style, className, }: SelectableObjectProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=SelectableObject.d.ts.map

package/dist/components/Misc/SelectableObject/SelectableObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelectableObject.d.ts","sourceRoot":"","sources":["../../../../src/components/Misc/SelectableObject/SelectableObject.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,MAAM,MAAM,sBAAsB,GAC9B,UAAU,GACV,WAAW,GACX,aAAa,GACb,cAAc,CAAC;AAEnB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC7C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,CACpB,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,KAAK,CAAC,YAAY,KACtB,IAAI,CAAC;IACV,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiBD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,gHAW9B,qBAAqB,4CAiGvB,CAAC"}

package/dist/components/Misc/SelectableObject/SelectableObject.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { primary, white } from '../../../constants/colors';
+const HANDLE_SIZE = 10;
+const HANDLE_HALF = HANDLE_SIZE / 2;
+const HANDLE_POSITIONS = {
+    'bottom-left': { cursor: 'nesw-resize', left: '0%', top: '100%' },
+    'bottom-right': { cursor: 'nwse-resize', left: '100%', top: '100%' },
+    'top-left': { cursor: 'nwse-resize', left: '0%', top: '0%' },
+    'top-right': { cursor: 'nesw-resize', left: '100%', top: '0%' },
+};
+const ANIMATION_NAME = 'taiv-ui-marching-ants';
+/**
+ * Chrome wrapper that renders an animated dashed selection border and four
+ * corner resize handles around arbitrary content. Purely presentational —
+ * drag + resize math lives in the consumer. SVG rather than CSS `dashed`
+ * borders because dash offsets are not animatable on standard borders.
+ */
+export const SelectableObject = ({ children, selected = true, showHandles = true, animated = true, color = primary[200], cursor, onSelect, onHandlePointerDown, style, className, }) => {
+    const resolvedCursor = cursor !== null && cursor !== void 0 ? cursor : (selected ? 'move' : 'pointer');
+    const interactive = Boolean(onSelect);
+    return (_jsxs("div", { className: className, ...(interactive
+            ? {
+                onClick: onSelect,
+                onKeyDown: (e) => {
+                    if (e.key === 'Enter' || e.key === ' ') {
+                        e.preventDefault();
+                        onSelect === null || onSelect === void 0 ? void 0 : onSelect(e);
+                    }
+                },
+                role: 'button',
+                tabIndex: 0,
+            }
+            : {}), style: {
+            cursor: resolvedCursor,
+            display: 'inline-block',
+            position: 'relative',
+            ...style,
+        }, children: [children, selected ? (_jsxs(_Fragment, { children: [_jsx("style", { children: `@keyframes ${ANIMATION_NAME} { to { stroke-dashoffset: -16; } }` }), _jsxs("svg", { role: 'presentation', style: {
+                            height: '100%',
+                            left: 0,
+                            overflow: 'visible',
+                            pointerEvents: 'none',
+                            position: 'absolute',
+                            top: 0,
+                            width: '100%',
+                        }, children: [_jsx("title", { children: "Selection border" }), _jsx("rect", { fill: 'none', height: '100%', stroke: color, strokeDasharray: '6 4', strokeWidth: 2, style: animated
+                                    ? { animation: `${ANIMATION_NAME} 1s linear infinite` }
+                                    : undefined, width: '100%', x: 0, y: 0 })] }), showHandles
+                        ? Object.keys(HANDLE_POSITIONS).map((handle) => {
+                            const pos = HANDLE_POSITIONS[handle];
+                            return (_jsx("button", { "aria-label": `Resize ${handle}`, onPointerDown: (e) => {
+                                    e.stopPropagation();
+                                    onHandlePointerDown === null || onHandlePointerDown === void 0 ? void 0 : onHandlePointerDown(handle, e);
+                                }, style: {
+                                    backgroundColor: white,
+                                    border: `2px solid ${color}`,
+                                    borderRadius: 2,
+                                    cursor: pos.cursor,
+                                    height: HANDLE_SIZE,
+                                    left: pos.left,
+                                    marginLeft: -HANDLE_HALF,
+                                    marginTop: -HANDLE_HALF,
+                                    padding: 0,
+                                    position: 'absolute',
+                                    top: pos.top,
+                                    width: HANDLE_SIZE,
+                                }, type: 'button' }, handle));
+                        })
+                        : null] })) : null] }));
+};

package/dist/components/Misc/SelectableObject/SelectableObject.stories.d.ts

@@ -0,0 +1,11 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { SelectableObject } from './SelectableObject';
+declare const meta: Meta<typeof SelectableObject>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const TextObject: Story;
+export declare const ImageObject: Story;
+export declare const ToggleSelection: Story;
+export declare const NoHandles: Story;
+export declare const StaticBorder: Story;
+//# sourceMappingURL=SelectableObject.stories.d.ts.map

package/dist/components/Misc/SelectableObject/SelectableObject.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelectableObject.stories.d.ts","sourceRoot":"","sources":["../../../../src/components/Misc/SelectableObject/SelectableObject.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAO5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,OAAO,gBAAgB,CAYvC,CAAC;AAEF,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAYnC,eAAO,MAAM,UAAU,EAAE,KAoBxB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAyBzB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,KA+B7B,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,KAiBvB,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,KAiB1B,CAAC"}