sv5ui 1.7.0 → 1.8.0

package/dist/Banner/Banner.svelte

@@ -0,0 +1,162 @@
+<script lang="ts" module>
+    import type { BannerProps } from './banner.types.js'
+
+    export type Props = BannerProps
+</script>
+
+<script lang="ts">
+    import { useId } from 'bits-ui'
+    import { bannerVariants, bannerDefaults } from './banner.variants.js'
+    import { getComponentConfig, iconsDefaults } from '../config.js'
+    import Icon from '../Icon/Icon.svelte'
+    import Button from '../Button/Button.svelte'
+
+    const config = getComponentConfig('banner', bannerDefaults)
+    const icons = getComponentConfig('icons', iconsDefaults)
+
+    let {
+        ref = $bindable(null),
+        as = 'div',
+        id,
+        title,
+        icon,
+        color = config.defaultVariants.color,
+        to,
+        target,
+        close = false,
+        closeIcon,
+        actions,
+        open = $bindable(true),
+        onClose,
+        class: className,
+        ui,
+        leading,
+        titleSlot,
+        actionsSlot,
+        closeSlot,
+        ...restProps
+    }: Props = $props()
+
+    const fallbackId = useId('banner-')
+    const effectiveId = $derived(id ?? fallbackId)
+
+    let dismissed = $state(false)
+
+    function storageKey(rawId: string) {
+        return `sv5ui-banner-${rawId.replace(/[^\w-]/g, '-')}`
+    }
+
+    $effect(() => {
+        void open
+        if (!id || typeof window === 'undefined') {
+            dismissed = false
+            return
+        }
+        dismissed = localStorage.getItem(storageKey(id)) === '1'
+    })
+
+    const visible = $derived(open && !dismissed)
+    const isClickable = $derived(!!to)
+    const resolvedCloseIcon = $derived(closeIcon ?? icons.close)
+    const closeButtonProps = $derived(!close ? null : close === true ? {} : close)
+
+    const classes = $derived.by(() => {
+        const slots = bannerVariants({ color, to: isClickable })
+        const c = config.slots
+        const u = ui ?? {}
+        return {
+            root: slots.root({ class: [c.root, className, u.root] }),
+            container: slots.container({ class: [c.container, u.container] }),
+            left: slots.left({ class: [c.left, u.left] }),
+            center: slots.center({ class: [c.center, u.center] }),
+            right: slots.right({ class: [c.right, u.right] }),
+            icon: slots.icon({ class: [c.icon, u.icon] }),
+            title: slots.title({ class: [c.title, u.title] }),
+            actions: slots.actions({ class: [c.actions, u.actions] }),
+            close: slots.close({ class: [c.close, u.close] })
+        }
+    })
+
+    function handleClose(event?: Event) {
+        event?.stopPropagation()
+        if (id && typeof window !== 'undefined') {
+            localStorage.setItem(storageKey(id), '1')
+        }
+        open = false
+        onClose?.()
+    }
+</script>
+
+{#if visible}
+    <svelte:element
+        this={as}
+        bind:this={ref}
+        class={classes.root}
+        role={isClickable ? undefined : 'region'}
+        aria-label={isClickable || titleSlot ? undefined : title}
+        data-banner-id={effectiveId}
+        {...restProps}
+    >
+        {#if isClickable}
+            <!-- eslint-disable svelte/no-navigation-without-resolve -->
+            <a
+                href={to}
+                {target}
+                class="absolute inset-0 z-0 rounded-[inherit] outline-none focus-visible:ring-2 focus-visible:ring-current focus-visible:ring-inset"
+                aria-label={title}
+                data-banner-link
+            ></a>
+            <!-- eslint-enable svelte/no-navigation-without-resolve -->
+        {/if}
+
+        <div class={classes.container}>
+            <div class={classes.left} aria-hidden="true"></div>
+
+            <div class={classes.center}>
+                {#if leading}
+                    {@render leading()}
+                {:else if icon}
+                    <Icon name={icon} class={classes.icon} />
+                {/if}
+
+                {#if titleSlot}
+                    {@render titleSlot()}
+                {:else if title}
+                    <span class={classes.title}>{title}</span>
+                {/if}
+
+                {#if actionsSlot}
+                    {@render actionsSlot()}
+                {:else if actions && actions.length > 0}
+                    <div
+                        class="{classes.actions} relative z-10"
+                        onclick={(e) => e.stopPropagation()}
+                        role="presentation"
+                    >
+                        {#each actions as action, i (i)}
+                            <Button size="xs" variant="ghost" color="surface" {...action} />
+                        {/each}
+                    </div>
+                {/if}
+            </div>
+
+            <div class="{classes.right} relative z-10">
+                {#if closeSlot}
+                    {@render closeSlot()}
+                {:else if closeButtonProps}
+                    <Button
+                        size="xs"
+                        variant="ghost"
+                        color="surface"
+                        square
+                        {...closeButtonProps}
+                        icon={closeButtonProps.icon ?? resolvedCloseIcon}
+                        class={classes.close}
+                        onclick={handleClose}
+                        aria-label={closeButtonProps['aria-label'] ?? 'Dismiss banner'}
+                    />
+                {/if}
+            </div>
+        </div>
+    </svelte:element>
+{/if}

package/dist/Banner/Banner.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { BannerProps } from './banner.types.js';
+export type Props = BannerProps;
+declare const Banner: import("svelte").Component<BannerProps, {}, "ref" | "open">;
+type Banner = ReturnType<typeof Banner>;
+export default Banner;

package/dist/Banner/banner.types.d.ts

@@ -0,0 +1,148 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes, HTMLAnchorAttributes } from 'svelte/elements';
+import type { ClassNameValue } from 'tailwind-merge';
+import type { BannerVariantProps, BannerSlots } from './banner.variants.js';
+import type { ButtonProps } from '../Button/button.types.js';
+/**
+ * Props for the Banner component.
+ *
+ * A full-width announcement bar typically rendered at the top of a page or
+ * layout. Supports optional `localStorage` persistence — once dismissed by a
+ * given `id`, the banner stays hidden across reloads.
+ *
+ * **Hydration note:** When a banner has been previously dismissed via `id`,
+ * users will see a one-frame flicker on initial render (server renders the
+ * banner, then `$effect` reads `localStorage` and hides it). Eliminating the
+ * flicker requires a SvelteKit prehydration script the consumer injects
+ * themselves — see the demo page for a recipe.
+ *
+ * @example
+ * ```svelte
+ * <Banner
+ *   id="announce-2026-q2"
+ *   icon="lucide:megaphone"
+ *   title="New features available — check the changelog!"
+ *   color="primary"
+ *   close
+ *   to="/changelog"
+ * />
+ * ```
+ */
+export interface BannerProps extends Omit<HTMLAttributes<HTMLElement>, 'class' | 'title' | 'id'> {
+    /**
+     * Bindable reference to the root DOM element.
+     */
+    ref?: HTMLElement | null;
+    /**
+     * The HTML element to render as the root.
+     * @default 'div'
+     */
+    as?: keyof HTMLElementTagNameMap;
+    /**
+     * Unique identifier used as the localStorage persistence key. When set,
+     * clicking the close button writes `sv5ui-banner-{id}` to localStorage
+     * and the banner remains hidden on subsequent loads.
+     *
+     * Without an explicit `id`, a stable per-instance id is generated via
+     * `useId()` (used for the `data-banner-id` DOM attribute), but **dismissal
+     * is session-only** — no localStorage interaction happens. Pass an
+     * explicit `id` to opt into cross-reload persistence.
+     *
+     * Allowed characters in the storage key: alphanumeric, underscore, dash.
+     * Other characters are replaced with `-`.
+     */
+    id?: string;
+    /**
+     * Banner text content.
+     */
+    title?: string;
+    /**
+     * Iconify icon name rendered before the title.
+     */
+    icon?: string;
+    /**
+     * Color theme. Applies background + foreground tokens.
+     * @default 'primary'
+     */
+    color?: NonNullable<BannerVariantProps['color']>;
+    /**
+     * When provided, the entire banner becomes a clickable link via an
+     * absolute-positioned overlay anchor. The `as` element stays unchanged
+     * (so close/action buttons inside aren't nested in an `<a>` — valid HTML).
+     * Pair with `target` for new-tab links.
+     */
+    to?: string;
+    /**
+     * Anchor `target` (e.g. `'_blank'`). Only honored when `to` is set.
+     */
+    target?: HTMLAnchorAttributes['target'];
+    /**
+     * Show close button. Pass `true` for default styling or a `ButtonProps`
+     * object to customize. When `id` is also set, dismissal persists across
+     * reloads via localStorage.
+     * @default false
+     */
+    close?: boolean | ButtonProps;
+    /**
+     * Override the close button icon.
+     * @default 'lucide:x' (from global icons config)
+     */
+    closeIcon?: string;
+    /**
+     * Action buttons rendered inline after the title. Each entry is spread
+     * onto a `<Button>` and accepts the full `ButtonProps` shape. Banner
+     * applies `size="xs" color="surface"` as the default — override any prop
+     * (variant, color, icon, to, etc.) per item.
+     *
+     * @example
+     * ```svelte
+     * <Banner
+     *   title="Update available"
+     *   actions={[
+     *     { label: 'Learn more', variant: 'outline' },
+     *     { label: 'Update now', trailingIcon: 'lucide:arrow-right' }
+     *   ]}
+     * />
+     * ```
+     */
+    actions?: ButtonProps[];
+    /**
+     * Bindable visibility. Set to `false` to hide externally without
+     * persisting (e.g. for analytics-driven banners). When the user clicks
+     * the close button, this is set to `false` automatically.
+     * @default true
+     */
+    open?: boolean;
+    /**
+     * Fired when the close button is clicked, before any localStorage
+     * write. Cannot prevent dismissal — use `open` binding if you need
+     * conditional dismissal.
+     */
+    onClose?: () => void;
+    /**
+     * Additional CSS classes for the root element.
+     */
+    class?: ClassNameValue;
+    /**
+     * Override classes for component slots.
+     */
+    ui?: Partial<Record<BannerSlots, ClassNameValue>>;
+    /**
+     * Custom leading content. Replaces the default `icon` rendering.
+     */
+    leading?: Snippet;
+    /**
+     * Custom title content. Replaces the default `title` text.
+     */
+    titleSlot?: Snippet;
+    /**
+     * Custom actions content. Replaces the default `actions` array rendering.
+     */
+    actionsSlot?: Snippet;
+    /**
+     * Custom close button content. When provided, the consumer is
+     * responsible for wiring up the dismiss action (typically by binding
+     * `open` externally).
+     */
+    closeSlot?: Snippet;
+}

package/dist/Banner/banner.types.js

@@ -0,0 +1 @@
+export {};

package/dist/Banner/banner.variants.d.ts

@@ -0,0 +1,293 @@
+import { type VariantProps } from 'tailwind-variants';
+export declare const bannerVariants: import("tailwind-variants").TVReturnType<{
+    color: {
+        primary: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        secondary: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        tertiary: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        success: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        warning: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        error: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        info: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        surface: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+    };
+    to: {
+        true: string;
+        false: string;
+    };
+}, {
+    root: string;
+    container: string;
+    left: string;
+    center: string;
+    right: string;
+    icon: string;
+    title: string;
+    actions: string[];
+    close: string;
+}, undefined, {
+    color: {
+        primary: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        secondary: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        tertiary: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        success: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        warning: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        error: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        info: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        surface: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+    };
+    to: {
+        true: string;
+        false: string;
+    };
+}, {
+    root: string;
+    container: string;
+    left: string;
+    center: string;
+    right: string;
+    icon: string;
+    title: string;
+    actions: string[];
+    close: string;
+}, import("tailwind-variants").TVReturnType<{
+    color: {
+        primary: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        secondary: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        tertiary: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        success: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        warning: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        error: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        info: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+        surface: {
+            root: string;
+            icon: string;
+            title: string;
+        };
+    };
+    to: {
+        true: string;
+        false: string;
+    };
+}, {
+    root: string;
+    container: string;
+    left: string;
+    center: string;
+    right: string;
+    icon: string;
+    title: string;
+    actions: string[];
+    close: string;
+}, undefined, unknown, unknown, undefined>>;
+export type BannerVariantProps = VariantProps<typeof bannerVariants>;
+export type BannerSlots = keyof ReturnType<typeof bannerVariants>;
+export declare const bannerDefaults: {
+    defaultVariants: import("tailwind-variants").TVDefaultVariants<{
+        color: {
+            primary: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            secondary: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            tertiary: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            success: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            warning: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            error: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            info: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            surface: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+        };
+        to: {
+            true: string;
+            false: string;
+        };
+    }, {
+        root: string;
+        container: string;
+        left: string;
+        center: string;
+        right: string;
+        icon: string;
+        title: string;
+        actions: string[];
+        close: string;
+    }, {
+        color: {
+            primary: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            secondary: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            tertiary: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            success: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            warning: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            error: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            info: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+            surface: {
+                root: string;
+                icon: string;
+                title: string;
+            };
+        };
+        to: {
+            true: string;
+            false: string;
+        };
+    }, {
+        root: string;
+        container: string;
+        left: string;
+        center: string;
+        right: string;
+        icon: string;
+        title: string;
+        actions: string[];
+        close: string;
+    }>;
+    slots: Partial<Record<BannerSlots, string>>;
+};

package/dist/Banner/banner.variants.js

@@ -0,0 +1,86 @@
+import { tv } from 'tailwind-variants';
+export const bannerVariants = tv({
+    slots: {
+        root: 'relative z-30 w-full transition-colors',
+        container: 'flex items-center justify-between gap-3 min-h-12 px-4 py-2',
+        left: 'hidden lg:flex lg:flex-1 lg:items-center',
+        center: 'flex items-center gap-2 min-w-0',
+        right: 'flex items-center justify-end gap-2 lg:flex-1',
+        icon: 'size-5 shrink-0 pointer-events-none',
+        title: 'text-sm font-medium truncate',
+        actions: [
+            'flex items-center gap-2 ms-2',
+            '[&_button]:text-inherit [&_button]:border-current/30 [&_button]:hover:bg-current/10'
+        ],
+        close: 'shrink-0 text-inherit hover:bg-current/10'
+    },
+    variants: {
+        color: {
+            primary: {
+                root: 'bg-primary text-on-primary',
+                icon: 'text-on-primary',
+                title: 'text-on-primary'
+            },
+            secondary: {
+                root: 'bg-secondary text-on-secondary',
+                icon: 'text-on-secondary',
+                title: 'text-on-secondary'
+            },
+            tertiary: {
+                root: 'bg-tertiary text-on-tertiary',
+                icon: 'text-on-tertiary',
+                title: 'text-on-tertiary'
+            },
+            success: {
+                root: 'bg-success text-on-success',
+                icon: 'text-on-success',
+                title: 'text-on-success'
+            },
+            warning: {
+                root: 'bg-warning text-on-warning',
+                icon: 'text-on-warning',
+                title: 'text-on-warning'
+            },
+            error: {
+                root: 'bg-error text-on-error',
+                icon: 'text-on-error',
+                title: 'text-on-error'
+            },
+            info: {
+                root: 'bg-info text-on-info',
+                icon: 'text-on-info',
+                title: 'text-on-info'
+            },
+            surface: {
+                root: 'bg-inverse-surface text-inverse-on-surface',
+                icon: 'text-inverse-on-surface',
+                title: 'text-inverse-on-surface'
+            }
+        },
+        to: {
+            true: '',
+            false: ''
+        }
+    },
+    compoundVariants: [
+        // -------------------------------------------------------------------
+        // Hover effects when banner is clickable (`to` is set)
+        // -------------------------------------------------------------------
+        { color: 'primary', to: true, class: { root: 'hover:bg-primary/90' } },
+        { color: 'secondary', to: true, class: { root: 'hover:bg-secondary/90' } },
+        { color: 'tertiary', to: true, class: { root: 'hover:bg-tertiary/90' } },
+        { color: 'success', to: true, class: { root: 'hover:bg-success/90' } },
+        { color: 'warning', to: true, class: { root: 'hover:bg-warning/90' } },
+        { color: 'error', to: true, class: { root: 'hover:bg-error/90' } },
+        { color: 'info', to: true, class: { root: 'hover:bg-info/90' } },
+        { color: 'surface', to: true, class: { root: 'hover:bg-inverse-surface/90' } }
+    ],
+    defaultVariants: {
+        color: 'primary',
+        to: false
+    }
+});
+export const bannerDefaults = {
+    defaultVariants: bannerVariants.defaultVariants,
+    slots: {}
+};

package/dist/Banner/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Banner } from './Banner.svelte';
+export type { BannerProps } from './banner.types.js';

package/dist/Banner/index.js

@@ -0,0 +1 @@
+export { default as Banner } from './Banner.svelte';