@loidolt/theme-svelte 0.5.0 → 0.6.0

package/dist/media-utils.js

@@ -0,0 +1,205 @@
+import { aspectRatio } from '@loidolt/theme-tokens';
+export const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/** A named frame (`'video'`) or any number or `'4 / 3'` string, as a width-over-height number. */
+export function resolveAspectRatio(ratio) {
+    if (typeof ratio === 'number')
+        return ratio;
+    const value = ratio in aspectRatio ? aspectRatio[ratio] : ratio;
+    const [width, height = '1'] = value.split('/').map((part) => part.trim());
+    const result = Number(width) / Number(height);
+    return Number.isFinite(result) && result > 0 ? result : 16 / 9;
+}
+/** `75` → `1:15`; `3725` → `1:02:05`. */
+export function formatDuration(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return '0:00';
+    const total = Math.floor(seconds);
+    const [hours, minutes, secs] = [
+        Math.floor(total / 3600),
+        Math.floor(total / 60) % 60,
+        total % 60,
+    ];
+    const tail = `${String(secs).padStart(2, '0')}`;
+    return hours > 0 ? `${hours}:${String(minutes).padStart(2, '0')}:${tail}` : `${minutes}:${tail}`;
+}
+/** `75` → `1 minute 15 seconds` — for `aria-valuetext`, where `1:15` is read as a ratio. */
+export function formatDurationSpoken(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return '0 seconds';
+    const total = Math.floor(seconds);
+    const units = [
+        [Math.floor(total / 3600), 'hour'],
+        [Math.floor(total / 60) % 60, 'minute'],
+        [total % 60, 'second'],
+    ];
+    const parts = units
+        .filter(([amount], index) => amount > 0 || (index === 2 && total === 0))
+        .map(([amount, unit]) => `${amount} ${unit}${amount === 1 ? '' : 's'}`);
+    return parts.join(' ');
+}
+const EXTENSIONS = {
+    image: ['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif', 'svg', 'bmp'],
+    video: ['mp4', 'webm', 'ogv', 'mov', 'm4v', 'm3u8'],
+    audio: ['mp3', 'wav', 'ogg', 'oga', 'm4a', 'aac', 'flac', 'opus'],
+};
+const MIME = {
+    m3u8: 'application/vnd.apple.mpegurl',
+    mp4: 'video/mp4',
+    m4v: 'video/mp4',
+    webm: 'video/webm',
+    ogv: 'video/ogg',
+    mov: 'video/quicktime',
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    oga: 'audio/ogg',
+    m4a: 'audio/mp4',
+    aac: 'audio/aac',
+    flac: 'audio/flac',
+    opus: 'audio/opus',
+};
+/** The lower-cased extension of a URL's last path segment, ignoring query and hash. */
+export function fileExtension(url) {
+    const segment = url.split(/[?#]/)[0].split('/').pop() ?? '';
+    const dot = segment.lastIndexOf('.');
+    return dot <= 0 || dot === segment.length - 1 ? '' : segment.slice(dot + 1).toLowerCase();
+}
+/** A MIME type for a file extension, when it is a media type this library knows. */
+export function guessMimeType(extension) {
+    return MIME[extension.toLowerCase()];
+}
+/** What a URL most likely points at, from its MIME type, embed host or extension. */
+export function inferMediaKind(url, mimeType) {
+    const family = mimeType?.split('/')[0];
+    if (family === 'image' || family === 'video' || family === 'audio')
+        return family;
+    if (mimeType && /mpegurl/i.test(mimeType))
+        return 'video';
+    if (parseEmbedUrl(url))
+        return 'embed';
+    const extension = fileExtension(url);
+    for (const [kind, list] of Object.entries(EXTENSIONS)) {
+        if (list.includes(extension))
+            return kind;
+    }
+    return null;
+}
+/** Whether a source is an HLS playlist (`.m3u8` or an HLS MIME type). */
+export function isHlsSource(source) {
+    const { src, type } = typeof source === 'string' ? { src: source, type: undefined } : source;
+    if (type)
+        return /mpegurl/i.test(type);
+    return fileExtension(src) === 'm3u8';
+}
+/** Normalises a `src` prop to a list of typed sources. */
+export function toMediaSources(src) {
+    if (Array.isArray(src))
+        return src;
+    return [{ src, type: guessMimeType(fileExtension(src)) }];
+}
+/** A `TimeRanges` object (e.g. `media.buffered`) as plain `[start, end]` pairs. */
+export function timeRangesToArray(ranges) {
+    if (!ranges)
+        return [];
+    return Array.from({ length: ranges.length }, (_, index) => [
+        ranges.start(index),
+        ranges.end(index),
+    ]);
+}
+const YOUTUBE_ID = /^[\w-]{11}$/;
+function parseStart(raw) {
+    if (!raw)
+        return undefined;
+    if (/^\d+$/.test(raw))
+        return Number(raw);
+    const match = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/.exec(raw);
+    if (!match || !match.slice(1).some(Boolean))
+        return undefined;
+    const [, hours = '0', minutes = '0', seconds = '0'] = match;
+    return Number(hours) * 3600 + Number(minutes) * 60 + Number(seconds);
+}
+/**
+ * Reads a YouTube or Vimeo page, share or embed URL. Returns `null` for anything else, so an
+ * arbitrary string can be tested safely.
+ */
+export function parseEmbedUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const host = parsed.hostname.replace(/^(www|m)\./, '');
+    const segments = parsed.pathname.split('/').filter(Boolean);
+    const fragment = new URLSearchParams(parsed.hash.slice(1));
+    const start = parseStart(parsed.searchParams.get('t') ?? parsed.searchParams.get('start') ?? fragment.get('t'));
+    const found = (provider, videoId) => videoId ? { provider, videoId, ...(start === undefined ? {} : { start }) } : null;
+    if (host === 'youtu.be') {
+        return found('youtube', YOUTUBE_ID.test(segments[0] ?? '') ? segments[0] : undefined);
+    }
+    if (host === 'youtube.com' || host === 'youtube-nocookie.com') {
+        const fromQuery = parsed.searchParams.get('v');
+        if (fromQuery && YOUTUBE_ID.test(fromQuery))
+            return found('youtube', fromQuery);
+        if (['embed', 'shorts', 'live', 'v'].includes(segments[0] ?? '')) {
+            return found('youtube', YOUTUBE_ID.test(segments[1] ?? '') ? segments[1] : undefined);
+        }
+        return null;
+    }
+    if (host === 'vimeo.com' || host === 'player.vimeo.com') {
+        return found('vimeo', [...segments].reverse().find((segment) => /^\d+$/.test(segment)));
+    }
+    return null;
+}
+/** The iframe `src` for a provider's player. */
+export function buildEmbedSrc(provider, videoId, { privacy = true, autoplay = false, start } = {}) {
+    const params = new URLSearchParams();
+    if (autoplay)
+        params.set('autoplay', '1');
+    if (provider === 'youtube') {
+        // Keep the end screen to this channel's videos rather than the whole site's.
+        params.set('rel', '0');
+        if (start !== undefined)
+            params.set('start', String(Math.floor(start)));
+        const host = privacy ? 'www.youtube-nocookie.com' : 'www.youtube.com';
+        return `https://${host}/embed/${encodeURIComponent(videoId)}?${params}`;
+    }
+    if (privacy)
+        params.set('dnt', '1');
+    const query = params.toString() ? `?${params}` : '';
+    // Vimeo reads the start time from the fragment, not the query.
+    const hash = start !== undefined ? `#t=${Math.floor(start)}s` : '';
+    return `https://player.vimeo.com/video/${encodeURIComponent(videoId)}${query}${hash}`;
+}
+/**
+ * YouTube's own still for a video. Loading it contacts Google before the user presses play, so
+ * `MediaEmbed` never fetches it by itself — pass it as `poster` only if that is acceptable.
+ */
+export function embedThumbnail(provider, videoId) {
+    return provider === 'youtube'
+        ? `https://i.ytimg.com/vi/${encodeURIComponent(videoId)}/hqdefault.jpg`
+        : null;
+}
+/** The preview image for a media item, if it has one. */
+export function mediaThumbnail(item) {
+    if (item.thumbnail)
+        return item.thumbnail;
+    if (item.kind === 'image')
+        return item.src;
+    if (item.kind === 'video' || item.kind === 'embed')
+        return item.poster;
+    return item.artwork;
+}
+/** A human name for a media item: its title, alt text or caption. */
+export function mediaLabel(item, index) {
+    const name = item.kind === 'image' ? item.alt || item.caption : (item.title ?? item.caption ?? undefined);
+    return name || `Item ${index === undefined ? '' : index + 1}`.trim();
+}
+/** A stable key for a media item. */
+export function mediaKey(item, index) {
+    if (item.id)
+        return item.id;
+    const source = item.kind === 'embed' ? item.url : item.src;
+    return `${typeof source === 'string' ? source : (source[0]?.src ?? '')}#${index}`;
+}

package/dist/media-zoom.svelte.d.ts

@@ -0,0 +1,33 @@
+import type { Attachment } from 'svelte/attachments';
+export interface MediaZoomOptions {
+    minScale?: number;
+    maxScale?: number;
+    /** How far one `zoomIn()` / `zoomOut()` moves. */
+    step?: number;
+    /** Where a double-click or double-tap zooms to. */
+    doubleTapScale?: number;
+    onScaleChange?: (scale: number) => void;
+}
+export interface MediaZoom {
+    /**
+     * Put on the frame the image sits in. Handles pinch, trackpad zoom (Ctrl + wheel), double-click
+     * and dragging to pan while zoomed.
+     */
+    readonly attach: Attachment<HTMLElement>;
+    readonly scale: number;
+    /** Pan offset in pixels. */
+    readonly x: number;
+    readonly y: number;
+    /** A CSS `transform` for the image. */
+    readonly transform: string;
+    readonly zoomed: boolean;
+    zoomIn(): void;
+    zoomOut(): void;
+    /** Back to 1× and centred. */
+    reset(): void;
+    /** Between 1× and `doubleTapScale`. */
+    toggle(): void;
+    destroy(): void;
+}
+/** Zoom and pan state for an image in a frame — the engine behind `Lightbox`'s zoom. */
+export declare function createMediaZoom(options?: MediaZoomOptions): MediaZoom;

package/dist/media-zoom.svelte.js

@@ -0,0 +1,126 @@
+import { onDestroy } from 'svelte';
+import { clamp } from './media-utils.js';
+/** Zoom and pan state for an image in a frame — the engine behind `Lightbox`'s zoom. */
+export function createMediaZoom(options = {}) {
+    const { minScale = 1, maxScale = 4, step = 0.5, doubleTapScale = 2, onScaleChange } = options;
+    if (!(minScale > 0 && maxScale >= minScale)) {
+        throw new RangeError('createMediaZoom: needs 0 < minScale <= maxScale');
+    }
+    let scale = $state(minScale);
+    let x = $state(0);
+    let y = $state(0);
+    let frame = null;
+    /** Keeps the scaled image covering the frame: no panning past its edges. */
+    const bound = () => {
+        const width = frame?.clientWidth ?? 0;
+        const height = frame?.clientHeight ?? 0;
+        const [limitX, limitY] = [((scale - 1) * width) / 2, ((scale - 1) * height) / 2];
+        x = clamp(x, -limitX, limitX);
+        y = clamp(y, -limitY, limitY);
+    };
+    const setScale = (next) => {
+        const value = clamp(next, minScale, maxScale);
+        if (value === scale)
+            return;
+        scale = value;
+        if (scale <= 1)
+            [x, y] = [0, 0];
+        bound();
+        onScaleChange?.(scale);
+    };
+    let detach;
+    const attach = (node) => {
+        frame = node;
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity -- pointer bookkeeping, never rendered
+        const pointers = new Map();
+        let pinch = null;
+        const distance = () => {
+            const [a, b] = [...pointers.values()];
+            return Math.hypot(a.x - b.x, a.y - b.y);
+        };
+        const onPointerDown = (event) => {
+            pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+            node.setPointerCapture?.(event.pointerId);
+            if (pointers.size === 2)
+                pinch = { distance: distance(), scale };
+        };
+        const onPointerMove = (event) => {
+            const previous = pointers.get(event.pointerId);
+            if (!previous)
+                return;
+            pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+            if (pinch && pointers.size === 2) {
+                setScale(pinch.scale * (distance() / (pinch.distance || 1)));
+            }
+            else if (pointers.size === 1 && scale > 1) {
+                x += event.clientX - previous.x;
+                y += event.clientY - previous.y;
+                bound();
+            }
+        };
+        const onPointerUp = (event) => {
+            pointers.delete(event.pointerId);
+            if (pointers.size < 2)
+                pinch = null;
+        };
+        const onWheel = (event) => {
+            // A plain wheel scrolls the page; trackpad pinches arrive as Ctrl + wheel.
+            if (!event.ctrlKey)
+                return;
+            event.preventDefault();
+            setScale(scale * Math.exp(-event.deltaY / 100));
+        };
+        const onDoubleClick = () => setScale(scale > 1 ? minScale : doubleTapScale);
+        node.addEventListener('pointerdown', onPointerDown);
+        node.addEventListener('pointermove', onPointerMove);
+        node.addEventListener('pointerup', onPointerUp);
+        node.addEventListener('pointercancel', onPointerUp);
+        node.addEventListener('wheel', onWheel, { passive: false });
+        node.addEventListener('dblclick', onDoubleClick);
+        detach = () => {
+            node.removeEventListener('pointerdown', onPointerDown);
+            node.removeEventListener('pointermove', onPointerMove);
+            node.removeEventListener('pointerup', onPointerUp);
+            node.removeEventListener('pointercancel', onPointerUp);
+            node.removeEventListener('wheel', onWheel);
+            node.removeEventListener('dblclick', onDoubleClick);
+            if (frame === node)
+                frame = null;
+            detach = undefined;
+        };
+        return () => detach?.();
+    };
+    const destroy = () => detach?.();
+    try {
+        onDestroy(destroy);
+    }
+    catch {
+        /* module scope: the caller owns `destroy()` */
+    }
+    return {
+        attach,
+        get scale() {
+            return scale;
+        },
+        get x() {
+            return x;
+        },
+        get y() {
+            return y;
+        },
+        get transform() {
+            return `translate(${x}px, ${y}px) scale(${scale})`;
+        },
+        get zoomed() {
+            return scale > 1;
+        },
+        zoomIn: () => setScale(scale + step),
+        zoomOut: () => setScale(scale - step),
+        reset() {
+            [x, y] = [0, 0];
+            setScale(minScale);
+        },
+        toggle: () => setScale(scale > 1 ? minScale : doubleTapScale),
+        destroy,
+    };
+}

package/dist/signature.d.ts

@@ -0,0 +1,55 @@
+/** One sampled point of a drawn stroke, in CSS pixels. `pressure` runs 0–1 (pens report it). */
+export interface SignaturePoint {
+    x: number;
+    y: number;
+    pressure?: number;
+}
+export interface SignatureStroke {
+    points: SignaturePoint[];
+    /** Line width in CSS pixels. */
+    width: number;
+}
+/** What a `SignaturePad` produces. */
+export interface SignatureValue {
+    mode: 'draw' | 'type';
+    /** Drawn strokes, for re-rendering or server-side checks. */
+    strokes?: SignatureStroke[];
+    /** The typed name, in `type` mode. */
+    typedName?: string;
+    /** The font family the typed name was set in. */
+    font?: string;
+    /** A PNG of the signature. */
+    dataUrl: string;
+    /** A scalable copy, in `draw` mode. */
+    svg?: string;
+    width: number;
+    height: number;
+}
+export type SignatureError = 'empty' | 'too-short';
+/** Total drawn length in CSS pixels — a scribble-versus-signature heuristic. */
+export declare function strokeLength(strokes: readonly SignatureStroke[]): number;
+/**
+ * An SVG path through a stroke's points, smoothed with quadratic curves through the midpoints —
+ * the same curve the canvas draws, so the SVG and PNG agree.
+ */
+export declare function strokePath(points: readonly SignaturePoint[]): string;
+/** The strokes as a standalone SVG document. */
+export declare function strokesToSvg(strokes: readonly SignatureStroke[], { width, height, color }: {
+    width: number;
+    height: number;
+    color?: string;
+}): string;
+/** Whether a signature is long enough to count, and why not if it is not. */
+export declare function validateSignature(input: {
+    mode: 'draw' | 'type';
+    strokes?: readonly SignatureStroke[];
+    typedName?: string;
+}, { minStrokeLength, minTypedLength, }?: {
+    minStrokeLength?: number;
+    minTypedLength?: number;
+}): {
+    valid: true;
+} | {
+    valid: false;
+    error: SignatureError;
+};

package/dist/signature.js

@@ -0,0 +1,52 @@
+/** Total drawn length in CSS pixels — a scribble-versus-signature heuristic. */
+export function strokeLength(strokes) {
+    let total = 0;
+    for (const { points } of strokes) {
+        for (let index = 1; index < points.length; index++) {
+            total += Math.hypot(points[index].x - points[index - 1].x, points[index].y - points[index - 1].y);
+        }
+    }
+    return total;
+}
+const round = (value) => Math.round(value * 100) / 100;
+/**
+ * An SVG path through a stroke's points, smoothed with quadratic curves through the midpoints —
+ * the same curve the canvas draws, so the SVG and PNG agree.
+ */
+export function strokePath(points) {
+    if (points.length === 0)
+        return '';
+    const [first] = points;
+    if (points.length === 1)
+        return `M${round(first.x)} ${round(first.y)}h0.01`;
+    let d = `M${round(first.x)} ${round(first.y)}`;
+    for (let index = 1; index < points.length - 1; index++) {
+        const [point, next] = [points[index], points[index + 1]];
+        d += `Q${round(point.x)} ${round(point.y)} ${round((point.x + next.x) / 2)} ${round((point.y + next.y) / 2)}`;
+    }
+    const last = points[points.length - 1];
+    return `${d}L${round(last.x)} ${round(last.y)}`;
+}
+/** The strokes as a standalone SVG document. */
+export function strokesToSvg(strokes, { width, height, color = '#20231d' }) {
+    const paths = strokes
+        .filter((stroke) => stroke.points.length)
+        .map((stroke) => `<path d="${strokePath(stroke.points)}" stroke-width="${round(stroke.width)}"/>`)
+        .join('');
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${round(width)} ${round(height)}" width="${round(width)}" height="${round(height)}" fill="none" stroke="${color}" stroke-linecap="round" stroke-linejoin="round">${paths}</svg>`;
+}
+/** Whether a signature is long enough to count, and why not if it is not. */
+export function validateSignature(input, { minStrokeLength = 20, minTypedLength = 2, } = {}) {
+    if (input.mode === 'type') {
+        const name = input.typedName?.trim() ?? '';
+        if (!name)
+            return { valid: false, error: 'empty' };
+        return name.length < minTypedLength ? { valid: false, error: 'too-short' } : { valid: true };
+    }
+    const strokes = input.strokes ?? [];
+    if (!strokes.some((stroke) => stroke.points.length))
+        return { valid: false, error: 'empty' };
+    return strokeLength(strokes) < minStrokeLength
+        ? { valid: false, error: 'too-short' }
+        : { valid: true };
+}

package/dist/toaster.svelte.d.ts

@@ -1,11 +1,25 @@
 import type { StatusVariant } from './types.js';
+/** A single follow-up the toast offers — "Undo", "View", "Retry". */
+export interface ToastAction {
+    label: string;
+    onAction: () => void;
+    /** Dismiss the toast after the action runs. Defaults to `true`. */
+    dismiss?: boolean;
+}
 export interface ToastOptions {
     title: string;
     description?: string;
     variant?: StatusVariant;
     /** Milliseconds before auto-dismiss. `0` or `Infinity` keeps the toast until dismissed. */
     duration?: number;
+    /**
+     * A button in the toast. Give an actionable toast enough `duration` to reach it (or `0`):
+     * WCAG 2.2.1 requires that people who need more time get it.
+     */
+    action?: ToastAction;
 }
+/** Everything but the title, for the status shortcuts. */
+export type ToastShortcutOptions = Omit<ToastOptions, 'title' | 'variant'>;
 export interface ToastRecord extends ToastOptions {
     id: string;
 }
@@ -20,6 +34,16 @@ export interface Toaster {
     readonly toasts: ToastRecord[];
     /** Adds a toast and returns its id. */
     push(toast: ToastOptions): string;
+    /**
+     * Changes a toast in place — "Uploading…" becoming "Uploaded". A new `duration` restarts its
+     * timer. Returns `false` when the toast is already gone.
+     */
+    update(id: string, patch: Partial<ToastOptions>): boolean;
+    success(title: string, options?: ToastShortcutOptions): string;
+    info(title: string, options?: ToastShortcutOptions): string;
+    warning(title: string, options?: ToastShortcutOptions): string;
+    /** Stays until dismissed unless you pass a `duration`: an error should not vanish unread. */
+    error(title: string, options?: ToastShortcutOptions): string;
     dismiss(id: string): void;
     clear(): void;
     /** Suspends every auto-dismiss timer — call on pointer enter / focus in. */

package/dist/toaster.svelte.js

@@ -72,6 +72,24 @@ export function createToaster(options = {}) {
         }
         return id;
     }
+    function update(id, patch) {
+        const index = toasts.findIndex((toast) => toast.id === id);
+        if (index === -1)
+            return false;
+        if (patch.duration !== undefined) {
+            if (!validDuration(patch.duration)) {
+                throw new RangeError('createToaster: toast `duration` must be non-negative or Infinity');
+            }
+            clearTimer(id);
+            if (!paused)
+                arm(id, patch.duration);
+            else
+                timers.set(id, { timeout: null, remaining: patch.duration, startedAt: 0 });
+        }
+        toasts[index] = { ...toasts[index], ...patch, id };
+        return true;
+    }
+    const shortcut = (variant, fallbackDuration) => (title, options = {}) => push({ duration: fallbackDuration, ...options, title, variant });
     const destroy = () => {
         for (const timer of timers.values()) {
             if (timer.timeout !== null)
@@ -92,6 +110,11 @@ export function createToaster(options = {}) {
             return toasts;
         },
         push,
+        update,
+        success: shortcut('success'),
+        info: shortcut('info'),
+        warning: shortcut('warning'),
+        error: shortcut('error', 0),
         dismiss,
         clear() {
             for (const toast of [...toasts])

package/dist/types.d.ts

@@ -5,9 +5,10 @@ export type ActionVariant = 'default' | 'primary' | 'quiet' | 'danger' | 'ghost'
 export type StatusVariant = 'info' | 'success' | 'warning' | 'error';
 /** Badge spans both sets: neutral, brand accent, or a status. */
 export type BadgeVariant = 'default' | 'accent' | StatusVariant;
-/** Shared control scale. Dialogs extend it with `xl`. */
+/** Shared control scale. Dialogs extend it with `xl` and `full`. */
 export type ControlSize = 'sm' | 'md' | 'lg';
-export type DialogSize = ControlSize | 'xl';
+/** `full` takes the viewport less a gutter — for editors and previews that need the room. */
+export type DialogSize = ControlSize | 'xl' | 'full';
 /**
  * Badges default to `inline`: a compact chip sized to the text it annotates, for table cells and
  * running copy. The `ControlSize` steps match the button scale so a badge standing in a row of
@@ -28,6 +29,17 @@ export interface Option<T extends string = string> {
     label: string;
     disabled?: boolean;
 }
+/** A labelled run of options: an `<optgroup>` in `Select`, a group heading in list popups. */
+export interface OptionGroup<T extends string = string> {
+    label: string;
+    options: Option<T>[];
+    /** Disables every option in the group. */
+    disabled?: boolean;
+}
+/** An option with a secondary line, for choices that need a sentence of explanation. */
+export interface ChoiceOption<T extends string = string> extends Option<T> {
+    description?: string;
+}
 /** `Option` is the single vocabulary for choice lists; `NavItem` is kept as a readable alias. */
 export type NavItem<T extends string = string> = Option<T>;
 /** One step in a breadcrumb trail. The final crumb is the current page and takes no `href`. */
@@ -43,14 +55,61 @@ export interface Disclosure<T extends string = string> {
 }
 /** A `DropdownMenu` row. Renders as a link when `href` is set. */
 export interface MenuItem<T extends string = string> extends Option<T> {
+    type?: 'item';
     href?: string;
-    /** Trailing hint, e.g. a keyboard shortcut. */
+    /** Trailing hint. Defaults to `shortcut` when that is set. */
     hint?: string;
+    /**
+     * The keyboard shortcut this action also has elsewhere in the app, in `aria-keyshortcuts`
+     * syntax (`'Control+D'`). Announced with the item and shown as its hint. The menu does not
+     * bind the key — your app does.
+     */
+    shortcut?: string;
+    /** Styles the row as destructive. Pair it with a confirmation for anything irreversible. */
+    destructive?: boolean;
     /** Leading visual. */
     icon?: Snippet;
     /** Draw a separator above this item. */
     separatorBefore?: boolean;
 }
+/** Rows under an optional heading, announced as one group. */
+export interface MenuGroup<T extends string = string> {
+    type: 'group';
+    label?: string;
+    items: MenuEntry<T>[];
+    separatorBefore?: boolean;
+}
+/** A toggle that stays in the menu, e.g. "Show grid". Reported through `onCheckedChange`. */
+export interface MenuCheckboxItem<T extends string = string> {
+    type: 'checkbox';
+    value: T;
+    label: string;
+    checked: boolean;
+    disabled?: boolean;
+    hint?: string;
+    separatorBefore?: boolean;
+}
+/** A one-of-many choice inside a menu, e.g. a sort order. Reported through `onValueChange`. */
+export interface MenuRadioGroup<T extends string = string> {
+    type: 'radio';
+    /** Identifies the group in `onValueChange`. */
+    name: string;
+    label?: string;
+    value: T | '';
+    options: Option<T>[];
+    separatorBefore?: boolean;
+}
+/** A nested menu that opens beside its row. */
+export interface MenuSub<T extends string = string> {
+    type: 'sub';
+    label: string;
+    icon?: Snippet;
+    disabled?: boolean;
+    items: MenuEntry<T>[];
+    separatorBefore?: boolean;
+}
+/** Anything `DropdownMenu`'s `items` can hold. A plain `MenuItem` needs no `type`. */
+export type MenuEntry<T extends string = string> = MenuItem<T> | MenuGroup<T> | MenuCheckboxItem<T> | MenuRadioGroup<T> | MenuSub<T>;
 /**
  * Payload of Bits UI's `child` snippet: spread `props` onto your own element to take over
  * rendering of a trigger without nesting an extra button inside it.

package/dist/utils.d.ts

@@ -3,3 +3,12 @@
  * Accepts the `class` prop of any component in this package.
  */
 export declare function cx(...values: Array<string | false | null | undefined>): string;
+/**
+ * Joins the ids of the elements that describe a control into one `aria-describedby` value, or
+ * `undefined` when there are none — an empty attribute is still an attribute.
+ *
+ * ```svelte
+ * <input aria-describedby={describedBy(hint && hintId, error && errorId)} />
+ * ```
+ */
+export declare function describedBy(...ids: Array<string | false | null | undefined>): string | undefined;

package/dist/utils.js

@@ -5,3 +5,14 @@
 export function cx(...values) {
     return values.filter(Boolean).join(' ');
 }
+/**
+ * Joins the ids of the elements that describe a control into one `aria-describedby` value, or
+ * `undefined` when there are none — an empty attribute is still an attribute.
+ *
+ * ```svelte
+ * <input aria-describedby={describedBy(hint && hintId, error && errorId)} />
+ * ```
+ */
+export function describedBy(...ids) {
+    return ids.filter(Boolean).join(' ') || undefined;
+}