@medalsocial/meda 1.7.0 → 2.1.0

package/dist/post-preview/platforms/twitter.js

@@ -0,0 +1,132 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Bookmark, Heart, MessageCircle, MoreHorizontal, Repeat2, Share } from 'lucide-react';
+import { useCallback, useRef, useState } from 'react';
+import { cn } from '../../lib/utils.js';
+import { Avatar } from '../internal/avatar.js';
+import { Textarea } from '../internal/textarea.js';
+export const DEFAULT_TWITTER_LABELS = {
+    placeholder: "What's happening?",
+    now: 'now',
+    moreOptions: 'More options',
+    reply: 'Reply',
+    retweet: 'Retweet',
+    like: 'Like',
+    save: 'Save',
+    share: 'Share',
+    viewAnalytics: 'View post analytics',
+};
+function useMentionTrigger(textareaRef, value, onChange) {
+    const [isOpen, setIsOpen] = useState(false);
+    const [query, setQuery] = useState('');
+    const triggerStartRef = useRef(null);
+    const close = useCallback(() => {
+        setIsOpen(false);
+        setQuery('');
+        triggerStartRef.current = null;
+    }, []);
+    const handleInput = useCallback(() => {
+        const ta = textareaRef.current;
+        if (!ta)
+            return;
+        const cursor = ta.selectionStart ?? 0;
+        const text = ta.value;
+        // Walk back from cursor to find `@` until whitespace or start.
+        let i = cursor - 1;
+        let foundAt = -1;
+        while (i >= 0) {
+            const ch = text[i];
+            if (ch === '@') {
+                // Must be at start or preceded by whitespace
+                if (i === 0 || /\s/.test(text[i - 1])) {
+                    foundAt = i;
+                }
+                break;
+            }
+            if (/\s/.test(ch))
+                break;
+            i -= 1;
+        }
+        if (foundAt === -1) {
+            if (isOpen)
+                close();
+            return;
+        }
+        triggerStartRef.current = foundAt;
+        setQuery(text.slice(foundAt + 1, cursor));
+        setIsOpen(true);
+    }, [textareaRef, isOpen, close]);
+    const insertMention = useCallback((mention) => {
+        const ta = textareaRef.current;
+        if (!ta)
+            return;
+        const start = triggerStartRef.current;
+        if (start === null)
+            return;
+        const cursor = ta.selectionStart ?? 0;
+        const before = value.slice(0, start);
+        const after = value.slice(cursor);
+        const formatted = mention.startsWith('@') ? mention : `@${mention}`;
+        const next = `${before}${formatted} ${after}`;
+        onChange?.(next);
+        close();
+    }, [textareaRef, value, onChange, close]);
+    return { isOpen, query, close, insertMention, handleInput };
+}
+function ContentWithMentions({ text, accent }) {
+    // Build typed parts with stable offsets so keys don't rely on positional index.
+    const segments = [];
+    let offset = 0;
+    for (const part of text.split(/(@[A-Za-z0-9_]+)/g)) {
+        if (!part)
+            continue;
+        segments.push({
+            key: `${offset}-${part}`,
+            isMention: /^@[A-Za-z0-9_]+$/.test(part),
+            value: part,
+        });
+        offset += part.length;
+    }
+    return (_jsx(_Fragment, { children: segments.map((seg) => seg.isMention ? (_jsx("span", { className: accent, children: seg.value }, seg.key)) : (_jsx("span", { children: seg.value }, seg.key))) }));
+}
+const THEME_CLASSES = {
+    light: {
+        surface: 'bg-white',
+        text: 'text-gray-900',
+        muted: 'text-gray-500',
+        border: 'border-gray-200',
+        mention: 'text-blue-500',
+    },
+    dim: {
+        surface: 'bg-[#15202B]',
+        text: 'text-white',
+        muted: 'text-gray-400',
+        border: 'border-[#38444D]',
+        mention: 'text-[#1D9BF0]',
+    },
+    'lights-out': {
+        surface: 'bg-black',
+        text: 'text-white',
+        muted: 'text-gray-500',
+        border: 'border-gray-800',
+        mention: 'text-blue-400',
+    },
+};
+/**
+ * Twitter / X feed-card preview. Supports light, dim, and lights-out
+ * themes plus an optional `@mention` picker render slot.
+ */
+export function TwitterPreview({ displayName, username, avatarUrl, content, mediaUrls, characterLimit, editable = false, onContentChange, className, labels, theme = 'lights-out', renderMentionPicker, }) {
+    const l = { ...DEFAULT_TWITTER_LABELS, ...labels };
+    const t = THEME_CLASSES[theme];
+    const formattedUsername = username.startsWith('@') ? username : `@${username}`;
+    const textareaRef = useRef(null);
+    const mention = useMentionTrigger(textareaRef, content, onContentChange);
+    return (_jsx("div", { "data-slot": "post-preview", "data-platform": "twitter", "data-theme": theme, className: cn('@container p-4 @[420px]:p-5', t.surface, t.text, className), children: _jsxs("div", { className: "flex gap-3", children: [_jsx(Avatar, { src: avatarUrl, displayName: displayName, className: "h-10 w-10 flex-shrink-0" }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("div", { className: "flex items-center gap-1 text-[15px]", children: [_jsx("span", { className: cn('truncate font-bold', t.text), children: displayName }), _jsx("span", { className: cn('truncate', t.muted), children: formattedUsername }), _jsx("span", { className: t.muted, children: "\u00B7" }), _jsx("span", { className: t.muted, children: l.now })] }), _jsx("button", { type: "button", "aria-label": l.moreOptions, className: cn('-m-1.5 inline-flex min-h-11 min-w-11 items-center justify-center rounded-full p-1.5', t.muted, theme === 'light' ? 'hover:bg-gray-100' : 'hover:bg-gray-800'), children: _jsx(MoreHorizontal, { className: "h-4 w-4" }) })] }), editable ? (_jsxs("div", { className: "relative", children: [_jsx(Textarea, { ref: textareaRef, value: content, onChange: (e) => onContentChange?.(e.target.value), onInput: mention.handleInput, onKeyUp: mention.handleInput, placeholder: l.placeholder, className: cn('mt-1 min-h-[60px] text-[15px]', t.text, theme === 'light' ? 'placeholder:text-gray-500' : 'placeholder:text-gray-500') }), renderMentionPicker && mention.isOpen
+                                    ? renderMentionPicker({
+                                        query: mention.query,
+                                        onPick: mention.insertMention,
+                                        onCancel: mention.close,
+                                    })
+                                    : null, characterLimit !== undefined && (_jsxs("div", { "data-slot": "twitter-character-counter", className: cn('mt-1 text-right text-xs', content.length > characterLimit ? 'text-red-500' : t.muted), children: [_jsx("span", { children: characterLimit - content.length }), _jsx("span", { className: "mx-1", children: "/" }), _jsx("span", { children: characterLimit })] }))] })) : (_jsx("p", { className: "mt-1 whitespace-pre-wrap break-words text-[15px]", children: _jsx(ContentWithMentions, { text: content, accent: t.mention }) })), mediaUrls && mediaUrls.length > 0 && (_jsx("div", { className: cn('mt-3 overflow-hidden rounded-2xl border', t.border, mediaUrls.length === 1 && 'aspect-video', mediaUrls.length >= 2 && 'grid aspect-video grid-cols-2 gap-0.5'), children: mediaUrls.slice(0, 4).map((url, i) => (_jsx("div", { className: cn('overflow-hidden bg-gray-800', mediaUrls.length === 1 && 'h-full', mediaUrls.length === 3 && i === 0 && 'row-span-2'), children: _jsx("img", { src: url, alt: `Media ${i + 1}`, loading: "lazy", decoding: "async", className: "h-full w-full object-cover" }) }, url))) })), _jsxs("div", { className: cn('mt-3 flex max-w-[425px] items-center justify-between @[420px]:max-w-[480px]', t.muted), children: [_jsxs("button", { type: "button", "aria-label": l.reply, className: "-m-2 inline-flex min-h-11 min-w-11 items-center gap-1 rounded-full p-2 hover:bg-blue-500/10 hover:text-blue-400", children: [_jsx(MessageCircle, { className: "h-[18px] w-[18px]" }), _jsx("span", { className: "text-[13px]", children: "0" })] }), _jsxs("button", { type: "button", "aria-label": l.retweet, className: "-m-2 inline-flex min-h-11 min-w-11 items-center gap-1 rounded-full p-2 hover:bg-green-500/10 hover:text-green-400", children: [_jsx(Repeat2, { className: "h-[18px] w-[18px]" }), _jsx("span", { className: "text-[13px]", children: "0" })] }), _jsxs("button", { type: "button", "aria-label": l.like, className: "-m-2 inline-flex min-h-11 min-w-11 items-center gap-1 rounded-full p-2 hover:bg-pink-500/10 hover:text-pink-400", children: [_jsx(Heart, { className: "h-[18px] w-[18px]" }), _jsx("span", { className: "text-[13px]", children: "0" })] }), _jsx("button", { type: "button", "aria-label": l.viewAnalytics, className: "-m-2 inline-flex min-h-11 min-w-11 items-center gap-1 rounded-full p-2 hover:bg-blue-500/10 hover:text-blue-400", children: _jsx("svg", { className: "h-[18px] w-[18px]", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { d: "M8.75 21V3h2v18h-2zM18 21V8.5h2V21h-2zM4 21l.004-10h2L6 21H4zm9.248 0v-7h2v7h-2z" }) }) }), _jsxs("div", { className: "flex items-center gap-1", children: [_jsx("button", { type: "button", "aria-label": l.save, className: "-m-2 inline-flex min-h-11 min-w-11 items-center justify-center rounded-full p-2 hover:bg-blue-500/10 hover:text-blue-400", children: _jsx(Bookmark, { className: "h-[18px] w-[18px]" }) }), _jsx("button", { type: "button", "aria-label": l.share, className: "-m-2 inline-flex min-h-11 min-w-11 items-center justify-center rounded-full p-2 hover:bg-blue-500/10 hover:text-blue-400", children: _jsx(Share, { className: "h-[18px] w-[18px]" }) })] })] })] })] }) }));
+}

package/dist/post-preview/platforms/youtube.d.ts

@@ -0,0 +1,17 @@
+import type { PostPreviewBaseProps } from '../types.js';
+export interface YouTubeLabels {
+    placeholder: string;
+    justNow: string;
+    like: string;
+    dislike: string;
+    share: string;
+    moreOptions: string;
+}
+export declare const DEFAULT_YOUTUBE_LABELS: YouTubeLabels;
+export interface YouTubePreviewProps extends PostPreviewBaseProps {
+    labels?: Partial<YouTubeLabels>;
+}
+/**
+ * YouTube community-post preview. Honors `.dark` for the dark variant.
+ */
+export declare function YouTubePreview({ displayName, username: _username, avatarUrl, content, mediaUrls, editable, onContentChange, className, labels, }: YouTubePreviewProps): import("react/jsx-runtime").JSX.Element;

package/dist/post-preview/platforms/youtube.js

@@ -0,0 +1,21 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MoreVertical, ThumbsDown, ThumbsUp } from 'lucide-react';
+import { cn } from '../../lib/utils.js';
+import { Avatar } from '../internal/avatar.js';
+import { Textarea } from '../internal/textarea.js';
+export const DEFAULT_YOUTUBE_LABELS = {
+    placeholder: 'Create a post...',
+    justNow: 'just now',
+    like: 'Like',
+    dislike: 'Dislike',
+    share: 'Share',
+    moreOptions: 'More options',
+};
+/**
+ * YouTube community-post preview. Honors `.dark` for the dark variant.
+ */
+export function YouTubePreview({ displayName, username: _username, avatarUrl, content, mediaUrls, editable = false, onContentChange, className, labels, }) {
+    const l = { ...DEFAULT_YOUTUBE_LABELS, ...labels };
+    return (_jsxs("div", { "data-slot": "post-preview", "data-platform": "youtube", className: cn('@container bg-white p-4 text-gray-900 @[420px]:text-[14px] dark:bg-[#0f0f0f] dark:text-white', className), children: [_jsxs("div", { className: "flex items-start justify-between", children: [_jsxs("div", { className: "flex gap-3", children: [_jsx(Avatar, { src: avatarUrl, displayName: displayName, className: "h-10 w-10" }), _jsx("div", { children: _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "font-medium text-[14px]", children: displayName }), _jsx("span", { className: "text-[12px] text-gray-500 dark:text-gray-400", children: l.justNow })] }) })] }), _jsx("button", { type: "button", "aria-label": l.moreOptions, className: "-m-2 inline-flex min-h-11 min-w-11 items-center justify-center rounded-full p-2 text-gray-600 hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-gray-800", children: _jsx(MoreVertical, { className: "h-5 w-5" }) })] }), editable ? (_jsx(Textarea, { value: content, onChange: (e) => onContentChange?.(e.target.value), placeholder: l.placeholder, className: "mt-3 min-h-[60px] text-[14px] placeholder:text-gray-500" })) : (_jsx("p", { className: "mt-3 whitespace-pre-wrap break-words text-[14px]", children: content })), mediaUrls && mediaUrls.length > 0 && (_jsx("div", { className: "mt-3 overflow-hidden rounded-xl", children: _jsx("div", { className: "aspect-video bg-gray-100 dark:bg-gray-800", children: _jsx("img", { src: mediaUrls[0], alt: "Media 1", loading: "lazy", decoding: "async", className: "h-full w-full object-cover" }) }) })), _jsxs("div", { className: "mt-4 flex items-center gap-2", children: [_jsxs("button", { type: "button", className: "inline-flex min-h-11 items-center gap-1 rounded-full bg-gray-100 px-3 py-1.5 hover:bg-gray-200 dark:bg-gray-800 dark:hover:bg-gray-700", "aria-label": l.like, children: [_jsx(ThumbsUp, { className: "h-4 w-4" }), _jsx("span", { className: "font-medium text-[13px]", children: "0" })] }), _jsx("button", { type: "button", "aria-label": l.dislike, className: "inline-flex min-h-11 min-w-11 items-center justify-center rounded-full bg-gray-100 p-2 hover:bg-gray-200 dark:bg-gray-800 dark:hover:bg-gray-700", children: _jsx(ThumbsDown, { className: "h-4 w-4" }) }), _jsxs("button", { type: "button", "aria-label": l.share, className: "inline-flex min-h-11 items-center gap-1 rounded-full bg-gray-100 px-3 py-1.5 hover:bg-gray-200 dark:bg-gray-800 dark:hover:bg-gray-700", children: [_jsx("svg", { className: "h-4 w-4", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { d: "M21 6h-2v9H6v2c0 .55.45 1 1 1h11l4 4V7c0-.55-.45-1-1-1zm-4 6V3c0-.55-.45-1-1-1H3c-.55 0-1 .45-1 1v14l4-4h10c.55 0 1-.45 1-1z" }) }), _jsx("span", { className: "font-medium text-[13px]", children: "0" })] })] })] }));
+}

package/dist/post-preview/post-preview.d.ts

@@ -0,0 +1,29 @@
+import type * as React from 'react';
+import type { BlueSkyPreviewProps, DiscordPreviewProps, FacebookPreviewProps, GenericPreviewProps, GoogleBusinessPreviewProps, InstagramPreviewProps, LinkedInPreviewProps, TelegramPreviewProps, ThreadsPreviewProps, TikTokPreviewProps, TwitterPreviewProps, YouTubePreviewProps } from './platforms/index.js';
+import type { PostPreviewSlots } from './types.js';
+export type PostPreviewProps = PostPreviewSlots & (({
+    platform: 'instagram';
+} & InstagramPreviewProps) | ({
+    platform: 'twitter';
+} & TwitterPreviewProps) | ({
+    platform: 'facebook';
+} & FacebookPreviewProps) | ({
+    platform: 'linkedin';
+} & LinkedInPreviewProps) | ({
+    platform: 'tiktok';
+} & TikTokPreviewProps) | ({
+    platform: 'youtube';
+} & YouTubePreviewProps) | ({
+    platform: 'threads';
+} & ThreadsPreviewProps) | ({
+    platform: 'bluesky';
+} & BlueSkyPreviewProps) | ({
+    platform: 'discord';
+} & DiscordPreviewProps) | ({
+    platform: 'telegram';
+} & TelegramPreviewProps) | ({
+    platform: 'google_business';
+} & GoogleBusinessPreviewProps) | ({
+    platform: 'generic';
+} & GenericPreviewProps));
+export declare function PostPreview(props: PostPreviewProps): React.ReactElement;

package/dist/post-preview/post-preview.js

@@ -0,0 +1,70 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { BlueSkyPreview } from './platforms/bluesky.js';
+import { DiscordPreview } from './platforms/discord.js';
+import { FacebookPreview } from './platforms/facebook.js';
+import { GenericPreview } from './platforms/generic.js';
+import { GoogleBusinessPreview } from './platforms/google-business.js';
+import { InstagramPreview } from './platforms/instagram.js';
+import { LinkedInPreview } from './platforms/linkedin.js';
+import { TelegramPreview } from './platforms/telegram.js';
+import { ThreadsPreview } from './platforms/threads.js';
+import { TikTokPreview } from './platforms/tiktok.js';
+import { TwitterPreview } from './platforms/twitter.js';
+import { YouTubePreview } from './platforms/youtube.js';
+export function PostPreview(props) {
+    const { platform, mode, renderEditor, renderMediaPicker, renderEmojiPicker, renderMentionPicker, onMediaUrlsChange, ...rest } = props;
+    const isEdit = mode === 'edit' || rest.editable === true;
+    const showToolbar = isEdit &&
+        (renderMediaPicker !== undefined ||
+            renderEmojiPicker !== undefined ||
+            renderMentionPicker !== undefined);
+    const platformProps = {
+        ...rest,
+        editable: isEdit && renderEditor === undefined,
+    };
+    const editorNode = renderEditor?.({
+        platform,
+        value: rest.content ?? '',
+        onChange: (next) => rest.onContentChange?.(next),
+    });
+    const toolbarNode = showToolbar ? (_jsxs("div", { className: "meda-post-preview__toolbar", role: "toolbar", "aria-label": "Post editor", children: [renderMediaPicker?.({
+                platform,
+                current: rest.mediaUrls,
+                onPick: (next) => onMediaUrlsChange?.(next),
+            }), renderEmojiPicker?.({
+                onSelect: (emoji) => rest.onContentChange?.((rest.content ?? '') + emoji),
+            }), renderMentionPicker?.({ platform })] })) : null;
+    const PreviewElement = renderPlatform(platform, platformProps);
+    if (editorNode === undefined && toolbarNode === null) {
+        return PreviewElement;
+    }
+    return (_jsxs("div", { className: "meda-post-preview", "data-platform": platform, children: [toolbarNode, editorNode, PreviewElement] }));
+}
+function renderPlatform(platform, props) {
+    switch (platform) {
+        case 'instagram':
+            return _jsx(InstagramPreview, { ...props });
+        case 'twitter':
+            return _jsx(TwitterPreview, { ...props });
+        case 'facebook':
+            return _jsx(FacebookPreview, { ...props });
+        case 'linkedin':
+            return _jsx(LinkedInPreview, { ...props });
+        case 'tiktok':
+            return _jsx(TikTokPreview, { ...props });
+        case 'youtube':
+            return _jsx(YouTubePreview, { ...props });
+        case 'threads':
+            return _jsx(ThreadsPreview, { ...props });
+        case 'bluesky':
+            return _jsx(BlueSkyPreview, { ...props });
+        case 'discord':
+            return _jsx(DiscordPreview, { ...props });
+        case 'telegram':
+            return _jsx(TelegramPreview, { ...props });
+        case 'google_business':
+            return _jsx(GoogleBusinessPreview, { ...props });
+        case 'generic':
+            return _jsx(GenericPreview, { ...props });
+    }
+}

package/dist/post-preview/public.d.ts

@@ -0,0 +1 @@
+export * from './index.js';

package/dist/post-preview/public.js

@@ -0,0 +1,6 @@
+// open/meda/src/post-preview/public.ts
+//
+// Re-exported into `src/index.ts` so consumers can import from the
+// package root as well as the subpath. Subpath import is preferred
+// for tree-shaking; root import is provided for convenience.
+export * from './index.js';

package/dist/post-preview/types.d.ts

@@ -0,0 +1,82 @@
+import type * as React from 'react';
+/**
+ * Public types for the post-preview surface.
+ *
+ * These types are framework-neutral and intentionally free of
+ * Convex / app-specific identifiers. Platform-specific extras
+ * (Telegram poll, Discord embeds, LinkedIn mentions) live next to
+ * their platform module.
+ */
+/**
+ * Platforms with a dedicated preview component. Any platform not in
+ * this list should use `GenericPreview` as a fallback.
+ */
+export type PlatformId = 'instagram' | 'twitter' | 'facebook' | 'linkedin' | 'tiktok' | 'youtube' | 'threads' | 'bluesky' | 'discord' | 'telegram' | 'google_business' | 'generic';
+export interface PostPreviewSlots {
+    /** When 'edit', enables editable mode. Sugar for `editable: true`. */
+    mode?: 'preview' | 'edit';
+    /** Replaces the platform's content textarea when in edit mode. */
+    renderEditor?: (ctx: {
+        platform: PlatformId;
+        value: string;
+        onChange: (next: string) => void;
+    }) => React.ReactNode;
+    /** Renders a media picker trigger in the edit toolbar. */
+    renderMediaPicker?: (ctx: {
+        platform: PlatformId;
+        current: string[] | undefined;
+        onPick: (next: string[]) => void;
+    }) => React.ReactNode;
+    /** Renders an emoji picker trigger in the edit toolbar. */
+    renderEmojiPicker?: (ctx: {
+        onSelect: (emoji: string) => void;
+    }) => React.ReactNode;
+    /**
+     * Renders a mention picker trigger in the edit toolbar. The consumer owns
+     * the mention search state and content insertion; the slot only receives
+     * the active platform so it can scope its own data source. Use
+     * `renderEditor` together with platform-specific mention props (e.g.
+     * `LinkedInMentionPickerContext`) to wire selection back into content.
+     */
+    renderMentionPicker?: (ctx: {
+        platform: PlatformId;
+    }) => React.ReactNode;
+    /** Called when renderMediaPicker invokes onPick. */
+    onMediaUrlsChange?: (mediaUrls: string[]) => void;
+}
+/**
+ * Visual frame mode for any platform preview.
+ * - `card` (default): fluid feed-card layout. Fits container width.
+ * - `device`: wraps in a phone shell with status bar / tab bar at
+ *   a native phone aspect ratio.
+ */
+export type PostPreviewFrame = 'card' | 'device';
+/**
+ * Shared props for every platform preview.
+ *
+ * Per-platform components extend this with their own optional extras
+ * (e.g. `TelegramPreviewProps` adds `poll`, `pinMessage`, `replyMarkup`).
+ */
+export interface PostPreviewBaseProps {
+    /** Channel display name (e.g. "Acme Studios"). */
+    displayName: string;
+    /** Channel handle/username; leading `@` is optional and stripped. */
+    username: string;
+    /** Channel avatar URL. Falls back to initials when omitted. */
+    avatarUrl?: string;
+    /** Post body text. Plain text; per-platform formatting (mentions,
+     * hashtags) is applied at render time. */
+    content: string;
+    /** Image / video URLs for the post media. */
+    mediaUrls?: string[];
+    /** Optional override for the per-platform character limit display. */
+    characterLimit?: number;
+    /** Visual frame mode. See `PostPreviewFrame`. */
+    frame?: PostPreviewFrame;
+    /** Enable inline editing of `content`. Requires `onContentChange`. */
+    editable?: boolean;
+    /** Called on every keystroke when `editable` is true. */
+    onContentChange?: (content: string) => void;
+    /** Class applied to the outer wrapper element. */
+    className?: string;
+}

package/dist/post-preview/types.js

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

package/dist/primitives/filter-rail.js

@@ -7,8 +7,23 @@ function FilterRailGroup({ title, description, children, className, ...props })
 }
 function FilterRailRoot({ title, description, search, actions, footer, children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...props }) {
     const titleId = useId();
-    const label = ariaLabel ?? (ariaLabelledBy ? undefined : typeof title === 'string' ? title : undefined);
-    const labelledBy = ariaLabelledBy ?? (label ? undefined : title ? titleId : undefined);
+    // Use `!== undefined` (not truthy) so that callers passing an explicit
+    // empty string clear the attribute instead of falling through to the
+    // title-derived fallback.
+    let label;
+    if (ariaLabel !== undefined) {
+        label = ariaLabel;
+    }
+    else if (ariaLabelledBy === undefined && typeof title === 'string') {
+        label = title;
+    }
+    let labelledBy;
+    if (ariaLabelledBy !== undefined) {
+        labelledBy = ariaLabelledBy;
+    }
+    else if (label === undefined && title) {
+        labelledBy = titleId;
+    }
     return (_jsxs("aside", { "data-slot": "filter-rail", "aria-label": label, "aria-labelledby": labelledBy, className: cn('flex min-h-0 w-full flex-col border-border bg-card text-card-foreground', className), ...props, children: [title || description || actions ? (_jsxs("div", { "data-slot": "filter-rail-header", className: "flex shrink-0 items-start justify-between gap-3 border-b border-border px-4 py-3", children: [_jsxs("div", { className: "min-w-0", children: [title ? (_jsx("h2", { id: titleId, "data-slot": "filter-rail-title", className: "text-sm font-semibold text-foreground", children: title })) : null, description ? (_jsx("p", { "data-slot": "filter-rail-description", className: "mt-0.5 text-xs text-muted-foreground", children: description })) : null] }), actions ? (_jsx("div", { "data-slot": "filter-rail-actions", className: "shrink-0", children: actions })) : null] })) : null, search ? (_jsx("div", { "data-slot": "filter-rail-search", className: "shrink-0 border-b border-border p-3", children: search })) : null, _jsx("div", { "data-slot": "filter-rail-content", className: "min-h-0 flex-1 space-y-5 overflow-y-auto p-4", children: children }), footer ? (_jsx("div", { "data-slot": "filter-rail-footer", className: "shrink-0 border-t border-border p-3", children: footer })) : null] }));
 }
 export const FilterRail = Object.assign(FilterRailRoot, {

package/dist/shell/app-shell-workspace.js

@@ -39,7 +39,7 @@ export function AppShellWorkspace({ iconRail, contextRail, rightPanel, workspace
     // <AppShell> wrapper already enforces h-screen for the workspace variant, so
     // nested viewport-height divs collapse cleanly — no double-scroll.
     const commandRegistry = useContext(CommandRegistryContext);
-    const shell = (_jsxs("div", { className: "flex h-screen flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions })) : (_jsx(ShellHeader, { globalActions: globalActions, headerCenter: headerCenter, appTabsRenderLink: appTabs?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter })), banners ? (_jsx("div", { "data-meda-banners": "", className: "flex-shrink-0", children: banners })) : (false), _jsxs("div", { className: "relative flex flex-1 overflow-hidden", children: [!isMobile && iconRail && (_jsx(IconRail, { mainItems: iconRail.mainItems, utilityItems: iconRail.utilityItems, footer: iconRail.footer, activeId: iconRail.activeId, renderLink: iconRail.renderLink })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId })), _jsx(ShellMain, { layout: mainLayout ?? 'workspace', className: mainClassName, children: children }), !isMobile && resolvedRightPanel.panelViews.length > 0 && (_jsx(RightPanel, { panelViews: staticPanelViews, defaultView: rightPanel?.defaultView }))] }), isMobile && hasDrawerContent && _jsx(MobileBottomNav, { items: navItems }), isMobile && hasDrawerContent && (_jsx(MobileDrawers, { menuItems: mobileMenuItems, menuActiveId: iconRail?.activeId, menuRenderLink: iconRail?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter, module: contextRail?.module, moduleAppId: contextRail?.appId, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }));
+    const shell = (_jsxs("div", { className: "flex h-screen flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions })) : (_jsx(ShellHeader, { globalActions: globalActions, headerCenter: headerCenter, appTabsRenderLink: appTabs?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter })), banners ? (_jsx("div", { "data-meda-banners": "", className: "flex-shrink-0", children: banners })) : (false), _jsxs("div", { className: "relative flex flex-1 overflow-hidden", children: [!isMobile && iconRail && (_jsx(IconRail, { mainItems: iconRail.mainItems, utilityItems: iconRail.utilityItems, footer: iconRail.footer, activeId: iconRail.activeId, renderLink: iconRail.renderLink })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId, header: contextRail.header, scroll: contextRail.scroll })), _jsx(ShellMain, { layout: mainLayout ?? 'workspace', className: mainClassName, children: children }), !isMobile && resolvedRightPanel.panelViews.length > 0 && (_jsx(RightPanel, { panelViews: staticPanelViews, defaultView: rightPanel?.defaultView }))] }), isMobile && hasDrawerContent && _jsx(MobileBottomNav, { items: navItems }), isMobile && hasDrawerContent && (_jsx(MobileDrawers, { menuItems: mobileMenuItems, menuActiveId: iconRail?.activeId, menuRenderLink: iconRail?.renderLink, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter, module: contextRail?.module, moduleAppId: contextRail?.appId, moduleHeader: contextRail?.header, moduleScroll: contextRail?.scroll, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }));
     return commandRegistry ? shell : _jsx(CommandPalette, { children: shell });
 }
 function buildMobileNavItems(contextRail, panelViews) {

package/dist/shell/context-rail.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { ContextModule, ShellLinkRenderArgs } from './types.js';
+import type { ContextModule, ContextRailHeader, ContextRailScroll, ShellLinkRenderArgs } from './types.js';
 export interface ContextRailProps {
     /** Drives the persistence key for layout state. */
     appId: string;
@@ -12,6 +12,8 @@ export interface ContextRailProps {
     /** Optional active item id for nav active state (preferred over useMedaShell().selection). */
     activeItemId?: string;
     renderLink?: (args: ShellLinkRenderArgs) => ReactNode;
+    header?: ContextRailHeader;
+    scroll?: ContextRailScroll;
     className?: string;
 }
-export declare function ContextRail({ appId, module, hidden, collapsible, activeItemId, renderLink, className, }: ContextRailProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ContextRail({ appId, module, hidden, collapsible, activeItemId, renderLink, header, scroll, className, }: ContextRailProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/shell/context-rail.js

@@ -75,7 +75,7 @@ function ContextRailToggle({ railId }) {
 // ---------------------------------------------------------------------------
 // ContextRail
 // ---------------------------------------------------------------------------
-export function ContextRail({ appId, module, hidden = false, collapsible = true, activeItemId, renderLink, className, }) {
+export function ContextRail({ appId, module, hidden = false, collapsible = true, activeItemId, renderLink, header = 'auto', scroll = 'auto', className, }) {
     const band = useShellViewport();
     const ctx = useMedaShell();
     // collapsible={false} means the rail must always render expanded — even if
@@ -92,6 +92,8 @@ export function ContextRail({ appId, module, hidden = false, collapsible = true,
     const [displayWidth, setDisplayWidth] = useState(null);
     const width = displayWidth ?? ctx.contextRail.width;
     const items = module?.items ?? [];
+    const hasRender = typeof module?.render === 'function';
+    const showHeader = header === 'visible' || (header === 'auto' && items.length > 0 && !hasRender);
     if (band === 'mobile')
         return null;
     if (hidden) {
@@ -113,22 +115,28 @@ export function ContextRail({ appId, module, hidden = false, collapsible = true,
     // transition then so the rail snaps to the cursor instead of lagging
     // behind it.
     const isDragging = displayWidth !== null;
-    return (_jsxs("aside", { id: railId, "data-testid": "context-rail", "aria-label": module.label, className: cn('relative h-full shrink-0 border-r border-shell-border bg-shell-context', !isDragging && 'transition-[width] duration-200 ease-in-out motion-reduce:transition-none', collapsed && 'w-0', className), style: { width: collapsed ? 0 : width }, children: [collapsible && _jsx(ContextRailToggle, { railId: railId }), _jsxs("div", { className: "h-full overflow-hidden", "aria-hidden": collapsed, inert: collapsed || undefined, children: [_jsxs("div", { className: "border-b border-shell-border px-4 py-3", children: [_jsx("h2", { className: "text-sm font-semibold text-foreground", children: module.label }), module.description && (_jsx("p", { className: "mt-0.5 text-xs text-muted-foreground", children: module.description }))] }), items.length > 0 && (_jsx("nav", { "aria-label": `${module.label} navigation`, className: "flex flex-col gap-0.5 p-2", children: items.map((item) => {
-                            const isActive = item.id === activeItemId;
-                            const klass = cn('flex items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors', isActive
-                                ? 'bg-primary/10 text-primary'
-                                : 'text-muted-foreground hover:bg-accent hover:text-foreground');
-                            const IconComp = item.icon;
-                            const inner = (_jsxs(_Fragment, { children: [_jsx(IconComp, { size: 16, "aria-hidden": "true", className: "shrink-0" }), _jsx("span", { className: "truncate", children: item.label }), item.shortcut && (_jsx("kbd", { className: "ml-auto font-mono text-[10px] text-muted-foreground", children: item.shortcut }))] }));
-                            const linkProps = {
-                                href: item.to,
-                                'aria-current': isActive ? 'page' : undefined,
-                                className: klass,
-                                children: inner,
-                            };
-                            if (renderLink) {
-                                return (_jsx(Fragment, { children: renderLink({ item, isActive, className: klass, children: inner, linkProps }) }, item.id));
-                            }
-                            return _jsx("a", { ...linkProps }, item.id);
-                        }) })), module.render?.({ workspaceId: ctx.workspace.id, appId })] }), !collapsed && (_jsx(ResizeHandle, { currentWidth: width, onResize: handleResize, onCommit: handleCommit }))] }));
+    return (_jsxs("aside", { id: railId, "data-testid": "context-rail", "aria-label": module.label, className: cn('relative h-full shrink-0 border-r border-shell-border bg-shell-context', !isDragging && 'transition-[width] duration-200 ease-in-out motion-reduce:transition-none', collapsed && 'w-0', className), style: { width: collapsed ? 0 : width }, children: [collapsible && _jsx(ContextRailToggle, { railId: railId }), _jsxs("div", { className: "flex h-full min-w-0 flex-col overflow-hidden", "aria-hidden": collapsed, inert: collapsed || undefined, children: [showHeader && (_jsxs("div", { className: "shrink-0 border-b border-shell-border px-4 py-3", children: [_jsx("h2", { className: "text-sm font-semibold text-foreground", children: module.label }), module.description && (_jsx("p", { className: "mt-0.5 text-xs text-muted-foreground", children: module.description }))] })), _jsxs("div", { "data-meda-context-rail-scroll-area": "", className: cn('min-h-0 flex-1', scroll === 'auto' ? 'overflow-y-auto overflow-x-hidden' : 'overflow-hidden'), children: [items.length > 0 && (_jsx("nav", { "aria-label": `${module.label} navigation`, className: "flex flex-col gap-0.5 p-2", children: items.map((item) => {
+                                    const isActive = item.id === activeItemId;
+                                    const klass = cn('flex items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors', isActive
+                                        ? 'bg-primary/10 text-primary'
+                                        : 'text-muted-foreground hover:bg-accent hover:text-foreground');
+                                    const IconComp = item.icon;
+                                    const inner = (_jsxs(_Fragment, { children: [_jsx(IconComp, { size: 16, "aria-hidden": "true", className: "shrink-0" }), _jsx("span", { className: "truncate", children: item.label }), item.shortcut && (_jsx("kbd", { className: "ml-auto font-mono text-[10px] text-muted-foreground", children: item.shortcut }))] }));
+                                    const linkProps = {
+                                        href: item.to,
+                                        'aria-current': isActive ? 'page' : undefined,
+                                        className: klass,
+                                        children: inner,
+                                    };
+                                    if (renderLink) {
+                                        return (_jsx(Fragment, { children: renderLink({
+                                                item,
+                                                isActive,
+                                                className: klass,
+                                                children: inner,
+                                                linkProps,
+                                            }) }, item.id));
+                                    }
+                                    return _jsx("a", { ...linkProps }, item.id);
+                                }) })), module.render?.({ workspaceId: ctx.workspace.id, appId })] })] }), !collapsed && (_jsx(ResizeHandle, { currentWidth: width, onResize: handleResize, onCommit: handleCommit }))] }));
 }

package/dist/shell/extras/shell-scrollable-content.js

@@ -1,7 +1,7 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 function joinClasses(...values) {
     return values.filter(Boolean).join(' ');
 }
 export function ShellScrollableContent({ children, desktopDockOffset = 0, layout, maxWidth, }) {
-    return (_jsx("main", { "data-testid": "shell-workspace-viewport", className: "shell-scrollbar-hidden absolute inset-0 min-w-0 overflow-y-auto overflow-x-hidden pb-[var(--bottom-nav-height)] transition-[padding] duration-300 ease-[cubic-bezier(0.22,1,0.36,1)] md:pb-0", style: desktopDockOffset > 0 ? { paddingRight: `${desktopDockOffset}px` } : undefined, children: layout === 'centered' ? (_jsx("div", { "data-testid": "shell-content-centered", className: "flex min-h-full items-center justify-center px-5 py-5 sm:px-6 sm:py-6 md:px-8 md:py-8 lg:px-10", children: _jsx("div", { className: "flex w-full max-w-3xl items-center justify-center", children: children }) })) : layout === 'fullbleed' ? (_jsx("div", { "data-testid": "shell-content-fullbleed", className: "mx-auto w-full px-5 py-5 sm:px-6 sm:py-6 md:px-8 md:py-8 lg:px-10", style: maxWidth ? { maxWidth: `${maxWidth}px` } : undefined, children: children })) : (_jsx("div", { "data-testid": "shell-content-workspace", className: joinClasses('mx-auto w-full px-5 py-5 sm:px-6 sm:py-6 md:px-8 md:py-8 lg:px-10'), style: maxWidth ? { maxWidth: `${maxWidth}px` } : undefined, children: children })) }));
+    return (_jsxs("main", { "data-testid": "shell-workspace-viewport", className: "shell-scrollbar-hidden absolute inset-0 min-w-0 overflow-y-auto overflow-x-hidden pb-[var(--bottom-nav-height)] transition-[padding] duration-300 ease-[cubic-bezier(0.22,1,0.36,1)] md:pb-0", style: desktopDockOffset > 0 ? { paddingRight: `${desktopDockOffset}px` } : undefined, children: [layout === 'centered' && (_jsx("div", { "data-testid": "shell-content-centered", className: "flex min-h-full items-center justify-center px-5 py-5 sm:px-6 sm:py-6 md:px-8 md:py-8 lg:px-10", children: _jsx("div", { className: "flex w-full max-w-3xl items-center justify-center", children: children }) })), layout === 'fullbleed' && (_jsx("div", { "data-testid": "shell-content-fullbleed", className: "mx-auto w-full px-5 py-5 sm:px-6 sm:py-6 md:px-8 md:py-8 lg:px-10", style: maxWidth ? { maxWidth: `${maxWidth}px` } : undefined, children: children })), layout !== 'centered' && layout !== 'fullbleed' && (_jsx("div", { "data-testid": "shell-content-workspace", className: joinClasses('mx-auto w-full px-5 py-5 sm:px-6 sm:py-6 md:px-8 md:py-8 lg:px-10'), style: maxWidth ? { maxWidth: `${maxWidth}px` } : undefined, children: children }))] }));
 }

package/dist/shell/extras/workbench-layout.js

@@ -13,17 +13,28 @@ function getWorkbenchMaxWidth(viewportBand) {
 }
 export function WorkbenchLayout({ viewportBand, main, aside, toolbar, className, }) {
     const maxWidth = getWorkbenchMaxWidth(viewportBand);
-    const layout = !aside
-        ? 'single'
-        : viewportBand === 'mobile' || viewportBand === 'tablet'
-            ? 'stacked'
-            : viewportBand === 'desktop'
-                ? 'split'
-                : 'multi-zone';
-    const columnStyle = layout === 'split'
-        ? { gridTemplateColumns: 'minmax(0, 1fr) minmax(280px, 320px)' }
-        : layout === 'multi-zone'
-            ? { gridTemplateColumns: 'minmax(0, 1fr) minmax(300px, 360px)' }
-            : undefined;
-    return (_jsxs("section", { "data-testid": "workbench-layout", "data-band": viewportBand, className: joinClasses('mx-auto flex w-full flex-col gap-6', className), style: maxWidth ? { maxWidth: `${maxWidth}px` } : undefined, children: [toolbar ? _jsx("div", { "data-testid": "workbench-toolbar", children: toolbar }) : null, _jsxs("div", { "data-testid": "workbench-columns", "data-layout": layout, className: joinClasses('w-full gap-5', layout === 'stacked' ? 'flex flex-col' : layout === 'single' ? 'flex flex-col' : 'grid'), style: columnStyle, children: [_jsx("div", { "data-testid": "workbench-main", className: "min-w-0", children: main }), aside ? (_jsx("aside", { "data-testid": "workbench-aside", className: "min-w-0", children: aside })) : null] })] }));
+    let layout;
+    if (!aside) {
+        layout = 'single';
+    }
+    else if (viewportBand === 'mobile' || viewportBand === 'tablet') {
+        layout = 'stacked';
+    }
+    else if (viewportBand === 'desktop') {
+        layout = 'split';
+    }
+    else {
+        layout = 'multi-zone';
+    }
+    let columnStyle;
+    if (layout === 'split') {
+        columnStyle = { gridTemplateColumns: 'minmax(0, 1fr) minmax(280px, 320px)' };
+    }
+    else if (layout === 'multi-zone') {
+        columnStyle = { gridTemplateColumns: 'minmax(0, 1fr) minmax(300px, 360px)' };
+    }
+    else {
+        columnStyle = undefined;
+    }
+    return (_jsxs("section", { "data-testid": "workbench-layout", "data-band": viewportBand, className: joinClasses('mx-auto flex w-full flex-col gap-6', className), style: maxWidth ? { maxWidth: `${maxWidth}px` } : undefined, children: [toolbar ? _jsx("div", { "data-testid": "workbench-toolbar", children: toolbar }) : null, _jsxs("div", { "data-testid": "workbench-columns", "data-layout": layout, className: joinClasses('w-full gap-5', layout === 'stacked' || layout === 'single' ? 'flex flex-col' : 'grid'), style: columnStyle, children: [_jsx("div", { "data-testid": "workbench-main", className: "min-w-0", children: main }), aside ? (_jsx("aside", { "data-testid": "workbench-aside", className: "min-w-0", children: aside })) : null] })] }));
 }

package/dist/shell/index.d.ts

@@ -27,5 +27,5 @@ export type { MedaShellProviderProps } from './shell-provider.js';
 export { MedaShellProvider, useMedaShell, useShellSelection } from './shell-provider.js';
 export { DefaultThemeProvider, ThemeToggle, useTheme } from './theme.js';
 export { NextThemesAdapter } from './theme-next-themes.js';
-export type { AppDefinition, AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellVariant, AppShellWorkspaceConfig, AppTabRenderLinkArgs, CommandDefinition, ContextItem, ContextModule, MobileBottomNavItem, PanelMode, PanelView, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, WorkspaceMenuItem, } from './types.js';
+export type { AppDefinition, AppShellAppTabsConfig, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellVariant, AppShellWorkspaceConfig, AppTabRenderLinkArgs, CommandDefinition, ContextItem, ContextModule, ContextRailHeader, ContextRailScroll, MobileBottomNavItem, PanelMode, PanelView, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, WorkspaceMenuItem, } from './types.js';
 export { useShellViewport } from './use-shell-viewport.js';

package/dist/shell/internal/mobile-drawers.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import type { IconRailItem, IconRailProps } from '../icon-rail.js';
-import type { ContextModule, PanelView, WorkspaceMenuItem } from '../types.js';
+import type { ContextModule, ContextRailHeader, ContextRailScroll, PanelView, WorkspaceMenuItem } from '../types.js';
 export interface MobileDrawersProps {
     /** Menu drawer source (icon-rail items). */
     menuItems?: IconRailItem[];
@@ -16,6 +16,10 @@ export interface MobileDrawersProps {
     module?: ContextModule;
     /** App id used when rendering module custom content. */
     moduleAppId?: string;
+    /** Header behavior mirrored from the desktop ContextRail. */
+    moduleHeader?: ContextRailHeader;
+    /** Scroll behavior mirrored from the desktop ContextRail. */
+    moduleScroll?: ContextRailScroll;
     /** Panels drawer source. */
     panelViews?: PanelView[];
     /**
@@ -33,4 +37,4 @@ export interface MobileDrawersProps {
  * any custom-content drawers. Mount once near the AppShell root; drawers
  * open/close via `ctx.mobileDrawer.open` provider state.
  */
-export declare function MobileDrawers({ menuItems, menuActiveId, menuRenderLink, workspaceMenuItems, workspaceMenuFooter, module, moduleAppId, panelViews, defaultView, customContent, }: MobileDrawersProps): import("react/jsx-runtime").JSX.Element;
+export declare function MobileDrawers({ menuItems, menuActiveId, menuRenderLink, workspaceMenuItems, workspaceMenuFooter, module, moduleAppId, moduleHeader, moduleScroll, panelViews, defaultView, customContent, }: MobileDrawersProps): import("react/jsx-runtime").JSX.Element;