@devxcrew/react-ui 0.0.0-stage → 0.1.7

package/src/layouts/mdi-main/mdi-topology.tsx

@@ -0,0 +1,297 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { InterfaceTopologyController, InterfaceTopologySection } from "../../features/interface-topology";
+
+const MdiTopologyContext = createContext<InterfaceTopologyController | null>(null);
+
+export const mdiTopologySections: readonly InterfaceTopologySection[] = [
+  {
+    id: "01",
+    technicalName: "mdi.commandBar.container",
+    name: "Command bar",
+    scope: "Application chrome",
+    description: "Holds navigation, identity, search, notifications, applications, and profile controls.",
+  },
+  {
+    id: "01.1",
+    technicalName: "mdi.commandBar.navigationToggle",
+    name: "Navigation toggle",
+    scope: "Command bar",
+    description: "Shows or hides the application navigation rail.",
+  },
+  {
+    id: "01.2",
+    technicalName: "mdi.commandBar.applicationIdentity",
+    name: "Application identity",
+    scope: "Command bar",
+    description: "Identifies the active CODEXSUN application.",
+  },
+  {
+    id: "01.3",
+    technicalName: "mdi.commandBar.globalSearch",
+    name: "Global search",
+    scope: "Command bar",
+    description: "Opens global search for the active workspace and application destinations.",
+  },
+  {
+    id: "01.3.1",
+    technicalName: "mdi.globalSearch.triggerButton",
+    name: "Global search button",
+    scope: "Global search",
+    description: "Opens global search by pointer or Control K.",
+  },
+  {
+    id: "01.3.2",
+    technicalName: "mdi.globalSearch.dialogPanel",
+    name: "Global search dialog",
+    scope: "Global search",
+    description: "Hosts the search input and matching destinations.",
+  },
+  {
+    id: "01.3.3",
+    technicalName: "mdi.globalSearch.queryInput",
+    name: "Search query input",
+    scope: "Global search dialog",
+    description: "Sends the current query to the application search contract.",
+  },
+  {
+    id: "01.3.4",
+    technicalName: "mdi.globalSearch.destinationList",
+    name: "Search destination list",
+    scope: "Global search dialog",
+    description: "Filters workspace navigation and application destinations.",
+  },
+  {
+    id: "01.4",
+    technicalName: "mdi.commandBar.notifications",
+    name: "Notifications",
+    scope: "Command bar",
+    description: "Opens application notifications.",
+  },
+  {
+    id: "01.4.1",
+    technicalName: "mdi.notifications.triggerButton",
+    name: "Notification button",
+    scope: "Notifications",
+    description: "Opens the notification panel and shows unread activity.",
+  },
+  {
+    id: "01.4.2",
+    technicalName: "mdi.notifications.dropdownPanel",
+    name: "Notification dropdown",
+    scope: "Notifications",
+    description: "Shows unread status and application notification content.",
+  },
+  {
+    id: "01.4.3",
+    technicalName: "mdi.notifications.notificationList",
+    name: "Notification list",
+    scope: "Notification dropdown",
+    description: "Lists application-owned notification records or the current empty state.",
+  },
+  {
+    id: "01.5",
+    technicalName: "mdi.commandBar.applicationSwitcher",
+    name: "Application switcher",
+    scope: "Command bar",
+    description: "Opens other registered applications.",
+  },
+  {
+    id: "01.5.1",
+    technicalName: "mdi.appSwitcher.triggerButton",
+    name: "Application launcher button",
+    scope: "Application switcher",
+    description: "Opens the application launcher with a nine-dot symbol.",
+  },
+  {
+    id: "01.5.2",
+    technicalName: "mdi.appSwitcher.dropdownPanel",
+    name: "Application launcher panel",
+    scope: "Application switcher",
+    description: "Shows the application launcher popover.",
+  },
+  {
+    id: "01.5.3",
+    technicalName: "mdi.appSwitcher.applicationGrid",
+    name: "Application grid",
+    scope: "Application launcher panel",
+    description: "Lists all application destinations in a three-column grid.",
+  },
+  {
+    id: "01.6",
+    technicalName: "mdi.commandBar.profileMenu",
+    name: "Profile menu",
+    scope: "Command bar",
+    description: "Opens profile and session actions.",
+  },
+  {
+    id: "01.6.1",
+    technicalName: "mdi.profile.triggerButton",
+    name: "User button",
+    scope: "Profile menu",
+    description: "Shows the user avatar or the first letter of the user name.",
+  },
+  {
+    id: "01.6.2",
+    technicalName: "mdi.profile.dropdownPanel",
+    name: "Profile dropdown",
+    scope: "Profile menu",
+    description: "Shows the current user identity and session actions.",
+  },
+  {
+    id: "01.6.3",
+    technicalName: "mdi.profile.userAvatar",
+    name: "User avatar",
+    scope: "Profile dropdown",
+    description: "Shows an image when supplied and a name initial otherwise.",
+  },
+  {
+    id: "01.6.4",
+    technicalName: "mdi.profile.sessionActions",
+    name: "Session actions",
+    scope: "Profile dropdown",
+    description: "Contains the shared sign-out action.",
+  },
+  {
+    id: "02",
+    technicalName: "mdi.navigation.sidebar",
+    name: "Application sidebar",
+    scope: "Application chrome",
+    description: "Contains the primary action, navigation, and feature settings.",
+  },
+  {
+    id: "02.2",
+    technicalName: "mdi.navigation.primaryAction",
+    name: "Primary action",
+    scope: "Application sidebar",
+    description: "Starts the primary workspace action.",
+  },
+  {
+    id: "02.3",
+    technicalName: "mdi.navigation.sectionList",
+    name: "Navigation sections",
+    scope: "Application sidebar",
+    description: "Lists application-owned destinations and actions.",
+  },
+  {
+    id: "02.4",
+    technicalName: "mdi.navigation.featureSettings",
+    name: "Feature settings",
+    scope: "Application sidebar",
+    description: "Opens shared MDI feature controls.",
+  },
+  {
+    id: "02.5",
+    technicalName: "mdi.navigation.railToggle",
+    name: "Sidebar rail toggle",
+    scope: "Application sidebar",
+    description: "Collapses or expands the sidebar.",
+  },
+  {
+    id: "03",
+    technicalName: "mdi.workspace.canvas",
+    name: "Workspace canvas",
+    scope: "Application workspace",
+    description: "Hosts the active application-owned page.",
+  },
+  {
+    id: "04",
+    technicalName: "mdi.statusBar.container",
+    name: "Status bar",
+    scope: "Application chrome",
+    description: "Shows runtime state and the active workspace name.",
+  },
+  {
+    id: "05",
+    technicalName: "mdi.appearance.control",
+    name: "Appearance control",
+    scope: "Application chrome",
+    description: "Opens density, canvas, and feature controls.",
+  },
+  {
+    id: "05.1",
+    technicalName: "mdi.appearance.themeSelector",
+    name: "Theme selector",
+    scope: "Appearance control",
+    description: "Selects the shared color mode and accent composition.",
+  },
+  {
+    id: "06",
+    technicalName: "mdi.features.workspace",
+    name: "Feature settings workspace",
+    scope: "Application settings",
+    description: "Controls the visibility of shared MDI features.",
+  },
+  {
+    id: "06.1",
+    technicalName: "mdi.features.backButton",
+    name: "Back to workspace",
+    scope: "Feature settings",
+    description: "Returns to the active application workspace.",
+  },
+  {
+    id: "06.2",
+    technicalName: "mdi.features.optionList",
+    name: "Feature option list",
+    scope: "Feature settings",
+    description: "Lists all configurable MDI features.",
+  },
+  {
+    id: "06.2.1",
+    technicalName: "mdi.features.topMenuSwitch",
+    name: "Top menu switch",
+    scope: "Feature option list",
+    description: "Shows or hides the shared top menu.",
+  },
+  {
+    id: "06.2.2",
+    technicalName: "mdi.features.notificationsSwitch",
+    name: "Notifications switch",
+    scope: "Feature option list",
+    description: "Shows or hides notifications.",
+  },
+  {
+    id: "06.2.3",
+    technicalName: "mdi.features.applicationSwitcher",
+    name: "Application switcher control",
+    scope: "Feature option list",
+    description: "Shows or hides the application switcher.",
+  },
+  {
+    id: "06.2.4",
+    technicalName: "mdi.features.profileMenuSwitch",
+    name: "Profile menu switch",
+    scope: "Feature option list",
+    description: "Shows or hides the profile menu.",
+  },
+  {
+    id: "06.2.5",
+    technicalName: "mdi.features.statusBarSwitch",
+    name: "Status bar switch",
+    scope: "Feature option list",
+    description: "Shows or hides the status bar.",
+  },
+  {
+    id: "06.2.6",
+    technicalName: "mdi.features.primaryActivityRailSwitch",
+    name: "Primary activity rail switch",
+    scope: "Feature option list",
+    description: "Shows or hides the primary Agent Workspace activity rail.",
+  },
+  {
+    id: "06.2.7",
+    technicalName: "mdi.features.secondaryUtilityRailSwitch",
+    name: "Secondary utility rail switch",
+    scope: "Feature option list",
+    description: "Shows or hides the secondary Agent Workspace utility rail.",
+  },
+];
+
+export function MdiTopologyProvider({ children, value }: { children: ReactNode; value: InterfaceTopologyController }) {
+  return <MdiTopologyContext.Provider value={value}>{children}</MdiTopologyContext.Provider>;
+}
+
+export function useMdiTopology() {
+  const topology = useContext(MdiTopologyContext);
+  if (!topology) throw new Error("useMdiTopology must be used inside MainWorkspace.");
+  return topology;
+}

package/src/layouts/mdi-main/mdi-tweak-panel.tsx

@@ -0,0 +1,104 @@
+import { SlidersHorizontalIcon } from 'lucide-react';
+
+import { Button } from '@devxcrew/react-ui/components/button';
+import {
+  Popover,
+  PopoverContent,
+  PopoverDescription,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverTrigger,
+} from '@devxcrew/react-ui/components/popover';
+import { cn } from '@devxcrew/react-ui/lib/utils';
+import { TopologyMarker, TopologyRegion } from '../../features/interface-topology';
+import { ThemeSelector } from '../../theme';
+import { useMdiTopology } from './mdi-topology';
+
+export type MdiCanvas = 'grid' | 'plain';
+export type MdiDensity = 'comfortable' | 'compact';
+
+type MdiTweakPanelProps = {
+  canvas: MdiCanvas;
+  density: MdiDensity;
+  onCanvasChange: (canvas: MdiCanvas) => void;
+  onDensityChange: (density: MdiDensity) => void;
+  onOpenFeatures: () => void;
+};
+
+export function MdiTweakPanel({
+  canvas,
+  density,
+  onCanvasChange,
+  onDensityChange,
+  onOpenFeatures,
+}: MdiTweakPanelProps) {
+  const topology = useMdiTopology();
+  return (
+    <div
+      className="fixed right-3 bottom-8 z-40 data-[ito-highlighted=true]:ring-2 data-[ito-highlighted=true]:ring-inset data-[ito-highlighted=true]:ring-violet-700"
+      {...topology.regionProps('05')}
+    >
+      <TopologyMarker id="05" topology={topology} />
+      <Popover>
+        <PopoverTrigger render={<Button variant="outline" size="icon" aria-label="Open workspace appearance" />}>
+          <SlidersHorizontalIcon />
+        </PopoverTrigger>
+        <PopoverContent align="end" side="top" className="w-64 gap-4">
+          <PopoverHeader>
+            <PopoverTitle>Workspace appearance</PopoverTitle>
+            <PopoverDescription>Adjust the MDI shell while its structure is reviewed.</PopoverDescription>
+          </PopoverHeader>
+          <TopologyRegion as="div" id="05.1" topology={topology}>
+            <ThemeSelector />
+          </TopologyRegion>
+          <OptionGroup
+            label="Density"
+            options={['compact', 'comfortable']}
+            value={density}
+            onChange={onDensityChange}
+          />
+          <OptionGroup label="Canvas" options={['plain', 'grid']} value={canvas} onChange={onCanvasChange} />
+          <Button variant="outline" className="w-full" onClick={onOpenFeatures}>
+            Feature settings
+          </Button>
+        </PopoverContent>
+      </Popover>
+    </div>
+  );
+}
+
+function OptionGroup<T extends string>({
+  label,
+  onChange,
+  options,
+  value,
+}: {
+  label: string;
+  onChange: (value: T) => void;
+  options: T[];
+  value: T;
+}) {
+  return (
+    <div className="flex flex-col gap-2">
+      <span className="text-sm font-medium">{label}</span>
+      <div className="grid grid-cols-2 gap-1 rounded-lg bg-muted p-1">
+        {options.map((option) => (
+          <button
+            key={option}
+            type="button"
+            aria-pressed={value === option}
+            className={cn(
+              'h-7 rounded-md px-2 text-sm capitalize transition-colors',
+              value === option
+                ? 'bg-background text-foreground shadow-sm'
+                : 'text-muted-foreground hover:text-foreground',
+            )}
+            onClick={() => onChange(option)}
+          >
+            {option}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/layouts/mdi-main/mdi-types.ts

@@ -0,0 +1,131 @@
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+import type { InterfaceTopologySection } from "../../features/interface-topology";
+import type { AgentWorkspaceProps } from "../agent-workspace";
+
+export type MdiFeatures = {
+  appSwitcher: boolean;
+  ito: boolean;
+  notifications: boolean;
+  primaryActivityRail: boolean;
+  profileMenu: boolean;
+  secondaryUtilityRail: boolean;
+  statusBar: boolean;
+  topMenu: boolean;
+};
+
+export type MdiFeatureKey = keyof MdiFeatures;
+
+export type MdiAppItem = {
+  active?: boolean;
+  href?: string;
+  icon: LucideIcon;
+  label: string;
+  onSelect?: () => void;
+};
+
+export type MdiNavigationItem = {
+  active?: boolean;
+  badge?: string | number;
+  children?: MdiNavigationItem[];
+  defaultOpen?: boolean;
+  href?: string;
+  icon?: LucideIcon;
+  label: string;
+  onSelect?: () => void;
+};
+
+export type MdiNavigationSection = {
+  defaultOpen?: boolean;
+  icon?: LucideIcon;
+  items: MdiNavigationItem[];
+  label?: string;
+};
+
+export type MdiPrimaryAction = {
+  icon?: LucideIcon;
+  label: string;
+  onSelect?: () => void;
+};
+
+export type MdiNotification = {
+  description?: string;
+  id: string;
+  read?: boolean;
+  severity?: "info" | "success" | "warning" | "error";
+  time?: string;
+  title: string;
+  onRead?: () => void;
+  onSelect?: () => void;
+};
+
+export type MdiUser = {
+  avatarUrl?: string;
+  email?: string;
+  initials: string;
+  name: string;
+  onManageProfile?: () => void;
+  onSignOut?: () => void;
+};
+
+export type MainWorkspaceProps = {
+  agentWorkspace?: Omit<AgentWorkspaceProps, "children" | "showPrimaryRail" | "showSecondaryRail">;
+  applicationIcon?: LucideIcon;
+  applicationLogoUrl?: string;
+  applicationId?: string;
+  applicationName?: string;
+  applicationHeaderStart?: ReactNode;
+  applicationHeaderEnd?: ReactNode;
+  applicationHeaderMeta?: ReactNode;
+  applicationHeaderBelow?: ReactNode;
+  applicationHeaderStatus?: ReactNode;
+  applicationHeaderTitle?: ReactNode;
+  showApplicationIdentity?: boolean;
+  showApplicationHeader?: boolean;
+  showWorkspaceTitleInHeader?: boolean;
+  apps?: MdiAppItem[];
+  children?: ReactNode;
+  contentClassName?: string;
+  defaultFeatures?: Partial<MdiFeatures>;
+  requiredFeatures?: Partial<MdiFeatures>;
+  defaultSidebarOpen?: boolean;
+  deskRegionId?: string;
+  embedded?: boolean;
+  navigation?: MdiNavigationSection[];
+  notificationCount?: number;
+  notifications?: readonly MdiNotification[];
+  primaryAction?: MdiPrimaryAction | null;
+  searchPlaceholder?: string;
+  searchValue?: string;
+  showMdiOverview?: boolean;
+  showTopologyTools?: boolean;
+  settingsContent?: (props: MdiSettingsContentProps) => ReactNode;
+  sidebarContent?: ReactNode;
+  sidebarContentClassName?: string;
+  sidebarFooter?: ReactNode | null;
+  sidebarFooterClassName?: string;
+  sidebarStateKey?: string;
+  statusLabel?: string;
+  statusEnd?: ReactNode;
+  topologySections?: readonly InterfaceTopologySection[];
+  user?: MdiUser;
+  workspaceTitle?: string;
+  onSearchChange?: (value: string) => void;
+};
+
+export type MdiSettingsContentProps = {
+  features: MdiFeatures;
+  onBack: () => void;
+  onFeatureChange: (feature: MdiFeatureKey, enabled: boolean) => void;
+};
+
+export const defaultMdiFeatures: MdiFeatures = {
+  appSwitcher: true,
+  ito: true,
+  notifications: true,
+  primaryActivityRail: true,
+  profileMenu: true,
+  secondaryUtilityRail: true,
+  statusBar: true,
+  topMenu: true,
+};

package/src/layouts/mdi-main/use-mdi-features.ts

@@ -0,0 +1,36 @@
+import { useEffect, useState } from 'react'
+
+import { defaultMdiFeatures, type MdiFeatureKey, type MdiFeatures } from './mdi-types'
+
+export function useMdiFeatures(
+  applicationId: string,
+  defaults: Partial<MdiFeatures> = {},
+): [MdiFeatures, (feature: MdiFeatureKey, enabled: boolean) => void] {
+  const storageKey = `codexsun.ui.mdi.features.${applicationId}`
+  const [features, setFeatures] = useState<MdiFeatures>(() =>
+    readFeatures(storageKey, { ...defaultMdiFeatures, ...defaults }),
+  )
+
+  useEffect(() => {
+    window.localStorage.setItem(storageKey, JSON.stringify(features))
+  }, [features, storageKey])
+
+  function setFeature(feature: MdiFeatureKey, enabled: boolean): void {
+    setFeatures((current) => ({ ...current, [feature]: enabled }))
+  }
+
+  return [features, setFeature]
+}
+
+function readFeatures(storageKey: string, defaults: MdiFeatures): MdiFeatures {
+  if (typeof window === 'undefined') return defaults
+
+  try {
+    const stored = JSON.parse(
+      window.localStorage.getItem(storageKey) ?? '{}',
+    ) as Partial<MdiFeatures>
+    return { ...defaults, ...stored }
+  } catch {
+    return defaults
+  }
+}

package/src/layouts/mdi-main/use-mdi-sidebar-state.ts

@@ -0,0 +1,59 @@
+import { useLayoutEffect, useRef, useState, type UIEventHandler } from 'react'
+
+export function usePersistentOpenState(storageKey: string | undefined, defaultOpen: boolean) {
+  const [open, setOpenState] = useState(() => readBoolean(storageKey) ?? defaultOpen)
+
+  const setOpen = (nextOpen: boolean) => {
+    setOpenState(nextOpen)
+    writeValue(storageKey, String(nextOpen))
+  }
+
+  return [open, setOpen] as const
+}
+
+export function usePersistentScrollPosition(storageKey: string | undefined) {
+  const ref = useRef<HTMLDivElement>(null)
+
+  useLayoutEffect(() => {
+    const scrollTop = readNumber(storageKey)
+    if (ref.current && scrollTop !== undefined) ref.current.scrollTop = scrollTop
+  }, [storageKey])
+
+  const onScroll: UIEventHandler<HTMLDivElement> = (event) => {
+    writeValue(storageKey, String(event.currentTarget.scrollTop))
+  }
+
+  return { onScroll, ref }
+}
+
+function readBoolean(storageKey: string | undefined) {
+  const value = readValue(storageKey)
+  if (value === 'true') return true
+  if (value === 'false') return false
+  return undefined
+}
+
+function readNumber(storageKey: string | undefined) {
+  const value = readValue(storageKey)
+  if (value === undefined) return undefined
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
+}
+
+function readValue(storageKey: string | undefined) {
+  if (!storageKey || typeof window === 'undefined') return undefined
+  try {
+    return window.sessionStorage.getItem(storageKey) ?? undefined
+  } catch {
+    return undefined
+  }
+}
+
+function writeValue(storageKey: string | undefined, value: string) {
+  if (!storageKey || typeof window === 'undefined') return
+  try {
+    window.sessionStorage.setItem(storageKey, value)
+  } catch {
+    // Keep navigation usable when browser storage is unavailable.
+  }
+}

package/src/layouts/site-header/announcement-bar.tsx

@@ -0,0 +1,55 @@
+import { ArrowRight, Sparkles, X } from 'lucide-react'
+import { useState } from 'react'
+import type { SiteAnnouncementProps } from './site-header-types'
+
+export function AnnouncementBar({
+  actionLabel,
+  actionUrl,
+  dismissible = true,
+  message,
+  onDismiss,
+  show = true,
+}: SiteAnnouncementProps) {
+  const [visible, setVisible] = useState(show)
+
+  if (!visible) return null
+
+  function handleDismiss() {
+    setVisible(false)
+    onDismiss?.()
+  }
+
+  return (
+    <div
+      aria-label="Announcement banner"
+      className="relative flex min-h-9 w-full items-center justify-center bg-primary px-4 py-1.5 text-xs font-medium text-primary-foreground select-none"
+      role="region"
+    >
+      <div className="flex flex-wrap items-center justify-center gap-2 text-center">
+        <Sparkles className="size-3.5 shrink-0 opacity-80" />
+        <span>{message}</span>
+
+        {actionLabel && actionUrl && (
+          <a
+            className="inline-flex items-center gap-1 font-semibold underline underline-offset-4 hover:opacity-90"
+            href={actionUrl}
+          >
+            {actionLabel}
+            <ArrowRight className="size-3" />
+          </a>
+        )}
+      </div>
+
+      {dismissible && (
+        <button
+          aria-label="Dismiss announcement"
+          className="absolute right-2 top-1/2 -translate-y-1/2 rounded p-1 opacity-70 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-primary-foreground"
+          type="button"
+          onClick={handleDismiss}
+        >
+          <X className="size-3.5" />
+        </button>
+      )}
+    </div>
+  )
+}