@gntik-ai/blocks 0.0.0-stage → 0.6.0

package/src/shell/AppSidebar/AppSidebar.tsx

@@ -0,0 +1,226 @@
+import { CircleHelp } from '@gntik-ai/icons';
+import {
+  Link,
+  Logo,
+  Meter,
+  NavList,
+  UserMenu,
+  WorkspaceSwitcher,
+  cn,
+  type NavGroup,
+  type NavItem,
+  type UserMenuEntry,
+  type UserMenuUser,
+  type Workspace,
+} from '@gntik-ai/ui';
+import { useState } from 'react';
+import {
+  appSidebarNavGroups,
+  appSidebarUsage,
+  appSidebarUser,
+  appSidebarWorkspaces,
+  type AppSidebarUsage,
+} from './fixtures';
+
+export interface AppSidebarHeaderProps {
+  /** Icon rail: shows only the brand mark. */
+  collapsed?: boolean;
+  /** Workspaces for the switcher; `null` shows the logo + wordmark instead. */
+  workspaces?: Workspace[] | null;
+  currentWorkspaceId?: string;
+  onWorkspaceChange?: (workspace: Workspace) => void;
+  onCreateWorkspace?: () => void;
+  className?: string;
+}
+
+/** Sidebar top: workspace switcher (or the brand logo), the brand mark alone in the icon rail. */
+export function AppSidebarHeader({
+  collapsed = false,
+  workspaces = appSidebarWorkspaces,
+  currentWorkspaceId,
+  onWorkspaceChange,
+  onCreateWorkspace,
+  className,
+}: AppSidebarHeaderProps) {
+  const [current, setCurrent] = useState(currentWorkspaceId ?? workspaces?.[0]?.id ?? '');
+  const currentId = currentWorkspaceId ?? current;
+  if (collapsed) return <Logo size={26} className={className} />;
+  if (!workspaces || workspaces.length === 0) return <Logo size={24} wordmark className={cn('px-1', className)} />;
+  return (
+    <WorkspaceSwitcher
+      className={cn('w-full', className)}
+      workspaces={workspaces}
+      currentId={currentId}
+      onCreate={onCreateWorkspace}
+      onSelect={(w) => {
+        setCurrent(w.id);
+        onWorkspaceChange?.(w);
+      }}
+    />
+  );
+}
+
+export interface AppSidebarNavProps {
+  groups?: NavGroup[];
+  currentHref?: string;
+  collapsed?: boolean;
+  /** Accessible name of the nav landmark. */
+  label?: string;
+  onNavigate?: (item: NavItem) => void;
+  className?: string;
+}
+
+/** Sidebar body: the NavList (icon rail with tooltips when collapsed). */
+export function AppSidebarNav({
+  groups = appSidebarNavGroups,
+  currentHref = '/projects',
+  collapsed = false,
+  label = 'Main',
+  onNavigate,
+  className,
+}: AppSidebarNavProps) {
+  return (
+    <NavList
+      groups={groups}
+      currentHref={currentHref}
+      collapsed={collapsed}
+      label={label}
+      onNavigate={onNavigate}
+      className={className}
+    />
+  );
+}
+
+export interface AppSidebarFooterProps {
+  collapsed?: boolean;
+  /** Plan usage meter; `null` hides it. */
+  usage?: AppSidebarUsage | null;
+  /** Help link; `null` hides it. */
+  helpHref?: string | null;
+  helpLabel?: string;
+  /** Signed-in user; `null` hides the user menu. */
+  user?: UserMenuUser | null;
+  userMenuItems?: UserMenuEntry[];
+  onSignOut?: () => void;
+  className?: string;
+}
+
+/** Sidebar bottom: usage meter, help link and the user menu (avatar only in the icon rail). */
+export function AppSidebarFooter({
+  collapsed = false,
+  usage = appSidebarUsage,
+  helpHref = '#help',
+  helpLabel = 'Help & docs',
+  user = appSidebarUser,
+  userMenuItems,
+  onSignOut,
+  className,
+}: AppSidebarFooterProps) {
+  return (
+    <div className={cn('flex flex-col gap-1.5', collapsed && 'items-center', className)}>
+      {usage && !collapsed && (
+        <div className="rounded-[10px] border border-border bg-card p-2.5">
+          <Meter
+            size="sm"
+            label={usage.label}
+            value={usage.value}
+            max={usage.max}
+            valueLabel={usage.valueLabel}
+            aria-valuetext={usage.valueLabel}
+          />
+        </div>
+      )}
+      {helpHref && (
+        <Link
+          href={helpHref}
+          tone="muted"
+          underline="none"
+          aria-label={collapsed ? helpLabel : undefined}
+          className={cn(
+            'flex h-[34px] items-center gap-2.5 rounded-lg px-2.5 text-[13px] font-medium hover:bg-accent/55 hover:text-foreground',
+            collapsed && 'size-9 justify-center px-0',
+          )}
+        >
+          <CircleHelp size={16} aria-hidden />
+          {!collapsed && helpLabel}
+        </Link>
+      )}
+      {user && (
+        <UserMenu
+          user={user}
+          items={userMenuItems}
+          onSignOut={onSignOut}
+          showName={!collapsed}
+          className={collapsed ? undefined : 'w-full justify-start'}
+        />
+      )}
+    </div>
+  );
+}
+
+export interface AppSidebarProps
+  extends
+    AppSidebarHeaderProps,
+    Omit<AppSidebarNavProps, 'className' | 'groups' | 'label'>,
+    Omit<AppSidebarFooterProps, 'className'> {
+  navGroups?: NavGroup[];
+  navLabel?: string;
+}
+
+/**
+ * Complete application sidebar column (chrome surface): workspace switcher header, NavList body
+ * and a footer with usage, help and the user menu. Inside SidebarLayout, use the parts
+ * (AppSidebarHeader / AppSidebarNav / AppSidebarFooter) in its three slots.
+ */
+export function AppSidebar({
+  collapsed = false,
+  workspaces,
+  currentWorkspaceId,
+  onWorkspaceChange,
+  onCreateWorkspace,
+  navGroups,
+  navLabel,
+  currentHref,
+  onNavigate,
+  usage,
+  helpHref,
+  helpLabel,
+  user,
+  userMenuItems,
+  onSignOut,
+  className,
+}: AppSidebarProps) {
+  return (
+    <div className={cn('flex h-full min-h-0 flex-col bg-chrome', collapsed ? 'w-16' : 'w-[248px]', className)}>
+      <div className={cn('flex shrink-0 items-center pt-4 pb-3', collapsed ? 'justify-center px-2' : 'px-3')}>
+        <AppSidebarHeader
+          collapsed={collapsed}
+          workspaces={workspaces}
+          currentWorkspaceId={currentWorkspaceId}
+          onWorkspaceChange={onWorkspaceChange}
+          onCreateWorkspace={onCreateWorkspace}
+        />
+      </div>
+      <div className={cn('min-h-0 flex-1 overflow-y-auto pt-1 pb-3', collapsed ? 'px-2' : 'px-3')}>
+        <AppSidebarNav
+          groups={navGroups}
+          label={navLabel}
+          currentHref={currentHref}
+          collapsed={collapsed}
+          onNavigate={onNavigate}
+        />
+      </div>
+      <div className={cn('shrink-0 border-t border-border/60 p-2.5', collapsed && 'px-2')}>
+        <AppSidebarFooter
+          collapsed={collapsed}
+          usage={usage}
+          helpHref={helpHref}
+          helpLabel={helpLabel}
+          user={user}
+          userMenuItems={userMenuItems}
+          onSignOut={onSignOut}
+        />
+      </div>
+    </div>
+  );
+}

package/src/shell/AppSidebar/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'App sidebar',
+  family: 'shell',
+  status: 'beta',
+  description:
+    'Application sidebar: workspace switcher (or logo) header, NavList body with icon-rail support, and a footer with plan usage, help link and user menu. Exposes header / nav / footer parts for the SidebarLayout slots.',
+  uses: ['WorkspaceSwitcher', 'Logo', 'NavList', 'Meter', 'Link', 'UserMenu'],
+};

package/src/shell/AppSidebar/fixtures.ts

@@ -0,0 +1,58 @@
+import {
+  Activity,
+  BarChart3,
+  CreditCard,
+  FolderKanban,
+  Home,
+  KeyRound,
+  Rocket,
+  Settings,
+  Users,
+} from '@gntik-ai/icons';
+import type { NavGroup, UserMenuUser, Workspace } from '@gntik-ai/ui';
+
+export const appSidebarNavGroups: NavGroup[] = [
+  {
+    label: 'Workspace',
+    items: [
+      { label: 'Overview', href: '/overview', icon: Home },
+      { label: 'Projects', href: '/projects', icon: FolderKanban, badge: 12 },
+      { label: 'Deployments', href: '/deployments', icon: Rocket, badge: 3 },
+      { label: 'Analytics', href: '/analytics', icon: BarChart3 },
+    ],
+  },
+  {
+    label: 'Admin',
+    collapsible: true,
+    items: [
+      { label: 'Activity', href: '/activity', icon: Activity },
+      { label: 'Members', href: '/members', icon: Users },
+      { label: 'Billing', href: '/billing', icon: CreditCard },
+      { label: 'API keys', href: '/api-keys', icon: KeyRound },
+      { label: 'Settings', href: '/settings', icon: Settings },
+    ],
+  },
+];
+
+export const appSidebarWorkspaces: Workspace[] = [
+  { id: 'acme', name: 'Acme Industries', meta: 'Enterprise · Owner' },
+  { id: 'northbeam', name: 'Northbeam Labs', meta: 'Pro · Admin' },
+  { id: 'personal', name: 'Personal', meta: 'Free · Owner' },
+];
+
+export interface AppSidebarUsage {
+  label: string;
+  value: number;
+  max: number;
+  /** Formatted value, e.g. "8.2k / 10k requests". */
+  valueLabel?: string;
+}
+
+export const appSidebarUsage: AppSidebarUsage = {
+  label: 'Monthly requests',
+  value: 8200,
+  max: 10000,
+  valueLabel: '8.2k / 10k',
+};
+
+export const appSidebarUser: UserMenuUser = { name: 'Dana Whitfield', email: 'dana@example.com' };

package/src/shell/AppTopbar/AppTopbar.test.tsx

@@ -0,0 +1,41 @@
+import { ThemeProvider } from '@gntik-ai/ui';
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { AppTopbar } from './AppTopbar';
+
+describe('AppTopbar', () => {
+  it('renders breadcrumb, environment, search, notifications, theme and user', async () => {
+    const { container } = render(
+      <ThemeProvider storageKey={null}>
+        <AppTopbar />
+      </ThemeProvider>,
+    );
+    const crumbs = screen.getByRole('navigation', { name: /breadcrumb/i });
+    expect(within(crumbs).getByText('web-frontend')).toBeInTheDocument();
+    expect(container.querySelector('[data-environment="production"]')).not.toBeNull();
+    expect(screen.getByRole('button', { name: /Search/ })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /notifications/i })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  }, 15_000);
+
+  it('opens the notifications and selects one', async () => {
+    const user = userEvent.setup();
+    const onNotificationSelect = vi.fn();
+    render(
+      <ThemeProvider storageKey={null}>
+        <AppTopbar onNotificationSelect={onNotificationSelect} search={null} theme="segmented" />
+      </ThemeProvider>,
+    );
+    await user.click(screen.getByRole('button', { name: /notifications/i }));
+    await user.click(await screen.findByText('api-gateway reached 97% of its monthly budget'));
+    expect(onNotificationSelect).toHaveBeenCalledWith(expect.objectContaining({ id: 'n1' }));
+  });
+
+  it('hides optional parts with null', () => {
+    const { container } = render(
+      <AppTopbar breadcrumbs={null} environment={null} search={null} notifications={null} theme={null} user={null} />,
+    );
+    expect(container.querySelectorAll('button')).toHaveLength(0);
+  });
+});

package/src/shell/AppTopbar/AppTopbar.tsx

@@ -0,0 +1,82 @@
+import {
+  Breadcrumbs,
+  NotificationsPopover,
+  ThemeCycleButton,
+  ThemeSwitcher,
+  UserMenu,
+  cn,
+  type BreadcrumbItem,
+  type NotificationItem,
+  type UserMenuEntry,
+  type UserMenuUser,
+} from '@gntik-ai/ui';
+import type { ReactNode } from 'react';
+import { appSidebarUser } from '../AppSidebar/fixtures';
+import { EnvironmentBadge, type EnvironmentBadgeProps } from '../EnvironmentBadge/EnvironmentBadge';
+import { GlobalSearch } from '../GlobalSearch/GlobalSearch';
+import { appTopbarBreadcrumbs, appTopbarNotifications } from './fixtures';
+
+export interface AppTopbarProps {
+  /** Location trail; `null` hides it. */
+  breadcrumbs?: BreadcrumbItem[] | null;
+  /** Replaces the breadcrumb (custom title, tabs…). */
+  breadcrumb?: ReactNode;
+  /** Environment chip after the breadcrumb; `null` hides it. */
+  environment?: EnvironmentBadgeProps | null;
+  /** Search control; defaults to GlobalSearch (⌘K). `null` hides it. */
+  search?: ReactNode;
+  /** Notifications; `null` hides the bell. */
+  notifications?: NotificationItem[] | null;
+  onNotificationSelect?: (notification: NotificationItem) => void;
+  onMarkAllRead?: () => void;
+  /** Theme control: a one-button cycle, the segmented switcher, or none. */
+  theme?: 'cycle' | 'segmented' | null;
+  /** Signed-in user; `null` hides the user menu. */
+  user?: UserMenuUser | null;
+  userMenuItems?: UserMenuEntry[];
+  onSignOut?: () => void;
+  className?: string;
+}
+
+/**
+ * Topbar contents: breadcrumb (+ environment chip) on the left; ⌘K search, notifications, theme
+ * and user menu on the right. Renders no <header>: put it in SidebarLayout's `topbar` slot or a
+ * header of your own.
+ */
+export function AppTopbar({
+  breadcrumbs = appTopbarBreadcrumbs,
+  breadcrumb,
+  environment = {},
+  search,
+  notifications = appTopbarNotifications,
+  onNotificationSelect,
+  onMarkAllRead,
+  theme = 'cycle',
+  user = appSidebarUser,
+  userMenuItems,
+  onSignOut,
+  className,
+}: AppTopbarProps) {
+  const searchNode = search === undefined ? <GlobalSearch className="hidden md:inline-flex" /> : search;
+  return (
+    <div className={cn('flex min-w-0 flex-1 items-center gap-2 lg:gap-3', className)}>
+      <div className="flex min-w-0 flex-1 items-center gap-2.5">
+        {breadcrumb ?? (breadcrumbs && <Breadcrumbs className="min-w-0" items={breadcrumbs} />)}
+        {environment && (
+          <EnvironmentBadge {...environment} className={cn('hidden sm:inline-flex', environment.className)} />
+        )}
+      </div>
+      {searchNode}
+      {notifications && (
+        <NotificationsPopover
+          notifications={notifications}
+          onSelect={onNotificationSelect}
+          onMarkAllRead={onMarkAllRead}
+        />
+      )}
+      {theme === 'cycle' && <ThemeCycleButton />}
+      {theme === 'segmented' && <ThemeSwitcher size="sm" className="hidden md:inline-flex" />}
+      {user && <UserMenu user={user} items={userMenuItems} onSignOut={onSignOut} />}
+    </div>
+  );
+}

package/src/shell/AppTopbar/block.meta.ts

@@ -0,0 +1,19 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'App topbar',
+  family: 'shell',
+  status: 'beta',
+  description:
+    'Topbar contents for the application shell: breadcrumb and environment chip, ⌘K global search, notifications popover, theme control and user menu.',
+  uses: [
+    'Breadcrumbs',
+    'Badge',
+    'CommandPalette',
+    'CommandPaletteTrigger',
+    'NotificationsPopover',
+    'ThemeCycleButton',
+    'ThemeSwitcher',
+    'UserMenu',
+  ],
+};

package/src/shell/AppTopbar/fixtures.ts

@@ -0,0 +1,22 @@
+import type { BreadcrumbItem, NotificationItem } from '@gntik-ai/ui';
+
+export const appTopbarBreadcrumbs: BreadcrumbItem[] = [
+  { label: 'Acme Industries', href: '/overview' },
+  { label: 'Projects', href: '/projects' },
+  { label: 'web-frontend', mono: true },
+];
+
+const MIN = 60_000;
+const NOW = Date.now();
+
+export const appTopbarNotifications: NotificationItem[] = [
+  {
+    id: 'n1',
+    tone: 'warning',
+    title: 'api-gateway reached 97% of its monthly budget',
+    body: 'Requests are throttled until the limit is raised.',
+    time: NOW - 2 * MIN,
+  },
+  { id: 'n2', tone: 'primary', title: 'Deployment web-frontend (build 418) succeeded', time: NOW - 18 * MIN },
+  { id: 'n3', tone: 'info', title: 'Sam Patel invited you to Data Platform', time: NOW - 65 * MIN, read: true },
+];

package/src/shell/EnvironmentBadge/EnvironmentBadge.test.tsx

@@ -0,0 +1,22 @@
+import { render, screen } from '@testing-library/react';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { EnvironmentBadge } from './EnvironmentBadge';
+
+describe('EnvironmentBadge', () => {
+  it('renders the default environment and region', async () => {
+    const { container } = render(<EnvironmentBadge />);
+    const badge = container.querySelector('[data-environment]');
+    expect(badge).toHaveAttribute('data-environment', 'production');
+    expect(badge).toHaveTextContent(/production.*eu-west/);
+    expect(screen.getByText('Environment:')).toHaveClass('sr-only');
+    await expectNoAxeViolations(container);
+  });
+
+  it('picks the tone from the environment and accepts an override', () => {
+    const { container, rerender } = render(<EnvironmentBadge environment="staging" region="us-east" />);
+    expect(container.textContent).toContain('staging');
+    rerender(<EnvironmentBadge environment="sandbox" region={null} tone="info" />);
+    expect(container.textContent).not.toContain('·');
+    expect(container.textContent).toContain('sandbox');
+  });
+});

package/src/shell/EnvironmentBadge/EnvironmentBadge.tsx

@@ -0,0 +1,55 @@
+import { Badge, cn } from '@gntik-ai/ui';
+
+export type EnvironmentTone = 'primary' | 'warning' | 'info' | 'neutral' | 'destructive';
+
+/** Default tone per environment name; anything else is neutral. */
+export const environmentTones: Record<string, EnvironmentTone> = {
+  production: 'primary',
+  prod: 'primary',
+  staging: 'warning',
+  preview: 'info',
+  development: 'neutral',
+  dev: 'neutral',
+};
+
+export interface EnvironmentBadgeProps {
+  /** Environment name, e.g. `production`, `staging`, `preview`. */
+  environment?: string;
+  /** Region or cluster shown after the environment, e.g. `eu-west`; `null` hides it. */
+  region?: string | null;
+  /** Overrides the tone looked up from `environmentTones`. */
+  tone?: EnvironmentTone;
+  /** Prefix read by screen readers only. */
+  srLabel?: string;
+  className?: string;
+}
+
+/** Environment + region chip for the topbar or a page header: "production · eu-west". */
+export function EnvironmentBadge({
+  environment = 'production',
+  region = 'eu-west',
+  tone,
+  srLabel = 'Environment:',
+  className,
+}: EnvironmentBadgeProps) {
+  const resolved = tone ?? environmentTones[environment.toLowerCase()] ?? 'neutral';
+  return (
+    <Badge
+      tone={resolved}
+      dot
+      data-environment={environment}
+      className={cn('font-mono text-[10.5px] whitespace-nowrap', className)}
+    >
+      <span className="sr-only">{srLabel} </span>
+      {environment}
+      {region && (
+        <>
+          <span aria-hidden className="opacity-60">
+            ·
+          </span>
+          <span className="sr-only">, region</span> {region}
+        </>
+      )}
+    </Badge>
+  );
+}

package/src/shell/EnvironmentBadge/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Environment badge',
+  family: 'shell',
+  status: 'beta',
+  description:
+    'Environment + region chip ("production · eu-west") for the topbar or a page header; tone follows the environment.',
+  uses: ['Badge'],
+};

package/src/shell/GlobalSearch/GlobalSearch.test.tsx

@@ -0,0 +1,28 @@
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { GlobalSearch } from './GlobalSearch';
+
+describe('GlobalSearch', () => {
+  it('renders the trigger with the shortcut hint', async () => {
+    const { container } = render(<GlobalSearch />);
+    expect(screen.getByRole('button', { name: /Search/ })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('⌘K opens it with recent and grouped results; choosing one reports its group', async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    render(<GlobalSearch onSelect={onSelect} />);
+    await user.keyboard('{Meta>}k{/Meta}');
+    const dialog = await screen.findByRole('dialog', { name: 'Global search' });
+    for (const heading of ['Recent', 'Pages', 'Records', 'Actions'])
+      expect(within(dialog).getByText(heading)).toBeInTheDocument();
+    await expectNoAxeViolations();
+    await user.keyboard('INV-2041');
+    await user.keyboard('{Enter}');
+    await waitFor(() => expect(onSelect).toHaveBeenCalledTimes(1));
+    expect(onSelect.mock.calls[0]?.[0]).toMatchObject({ id: 'record-inv-2041' });
+    expect(onSelect.mock.calls[0]?.[1]).toBe('records');
+  }, 15_000);
+});

package/src/shell/GlobalSearch/GlobalSearch.tsx

@@ -0,0 +1,80 @@
+import { CommandPalette, CommandPaletteTrigger, type CommandGroup, type CommandItem, useI18n } from '@gntik-ai/ui';
+import { globalSearchActions, globalSearchPages, globalSearchRecent, globalSearchRecords } from './fixtures';
+
+export type GlobalSearchGroup = 'pages' | 'records' | 'actions' | 'recent';
+
+export interface GlobalSearchProps {
+  pages?: CommandItem[];
+  records?: CommandItem[];
+  actions?: CommandItem[];
+  /** Shown first while the query is empty. */
+  recent?: CommandItem[];
+  /** Called with every chosen item and the group it came from (after the item's own onSelect). */
+  onSelect?: (item: CommandItem, group: GlobalSearchGroup) => void;
+  /** Group headings. */
+  labels?: Partial<Record<GlobalSearchGroup, string>>;
+  /** Registers ⌘K / Ctrl+K. */
+  shortcut?: boolean;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  placeholder?: string;
+  /** Text of the trigger button. */
+  triggerLabel?: string;
+  /** Classes for the trigger (e.g. `hidden md:inline-flex`). */
+  className?: string;
+}
+
+/** ⌘K search: a CommandPalette pre-wired with recent items and Pages / Records / Actions groups. */
+export function GlobalSearch({
+  pages = globalSearchPages,
+  records = globalSearchRecords,
+  actions = globalSearchActions,
+  recent = globalSearchRecent,
+  onSelect,
+  labels,
+  shortcut = true,
+  open,
+  defaultOpen,
+  onOpenChange,
+  placeholder: placeholderProp,
+  triggerLabel: triggerLabelProp,
+  className,
+}: GlobalSearchProps) {
+  const { t } = useI18n();
+  const placeholder = placeholderProp ?? t('globalSearch.placeholder');
+  const triggerLabel = triggerLabelProp ?? t('common.search');
+  const l: Record<GlobalSearchGroup, string> = {
+    pages: labels?.pages ?? t('globalSearch.pages'),
+    records: labels?.records ?? t('globalSearch.records'),
+    actions: labels?.actions ?? t('globalSearch.actions'),
+    recent: labels?.recent ?? t('commandPalette.recent'),
+  };
+  const origin = new Map<string, GlobalSearchGroup>();
+  const tag = (items: CommandItem[], group: GlobalSearchGroup) => {
+    for (const item of items) if (!origin.has(item.id)) origin.set(item.id, group);
+    return items;
+  };
+  const groups: CommandGroup[] = [
+    { label: l.pages, items: tag(pages, 'pages') },
+    { label: l.records, items: tag(records, 'records') },
+    { label: l.actions, items: tag(actions, 'actions') },
+  ].filter((g) => g.items.length > 0);
+  for (const item of recent) if (!origin.has(item.id)) origin.set(item.id, 'recent');
+  return (
+    <CommandPalette
+      groups={groups}
+      recent={recent}
+      recentLabel={l.recent}
+      shortcut={shortcut}
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      placeholder={placeholder}
+      label={t('globalSearch.label')}
+      onSelect={(item) => onSelect?.(item, origin.get(item.id) ?? 'recent')}
+    >
+      <CommandPaletteTrigger className={className}>{triggerLabel}</CommandPaletteTrigger>
+    </CommandPalette>
+  );
+}

package/src/shell/GlobalSearch/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Global search',
+  family: 'shell',
+  status: 'beta',
+  description:
+    '⌘K search button opening a CommandPalette pre-wired with recent items and grouped results: pages, records and actions.',
+  uses: ['CommandPalette', 'CommandPaletteTrigger', 'Kbd'],
+};