DesktopShell

Code

import { FolderIcon } from "lucide-react";import { DesktopAppIcon, DesktopShell } from "@fadymondy/nasaq/web";const apps = [  { id: "files", title: "Files", icon: <DesktopAppIcon><FolderIcon /></DesktopAppIcon>, content: <p>Files</p>, single: true },];export function Desktop() {  return <div className="h-dvh"><DesktopShell apps={apps} /></div>;}

Apps & Platforms · beta

Live examples and controls: DesktopShell in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/desktop-os-shell.json

A desktop metaphor for admin tools and demos. DesktopShell draws a wallpaper, a menu bar (built on Menubar), a dock and a launchpad, and manages floating windows. Apps are plain React nodes and the window list is plain data (DesktopWindowState[]), controlled or not. DesktopMenuBar, DesktopDock and DesktopLaunchpad are exported to build a different arrangement.

When to useCopy Anchor Link

• A multi-app workspace where users keep several tools open at once.
• A product demo or a kiosk that should feel like an operating system.

When not to useCopy Anchor Link

• A normal page layout: use the app shell and navigation components.
• One modal task: use Dialog.

ImportCopy Anchor Link

import { DesktopAppIcon, DesktopShell } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { FolderIcon } from "lucide-react";
import { DesktopAppIcon, DesktopShell } from "@fadymondy/nasaq/web";

const apps = [
  { id: "files", title: "Files", icon: <DesktopAppIcon><FolderIcon /></DesktopAppIcon>, content: <p>Files</p>, single: true },
];

export function Desktop() {
  return <div className="h-dvh"><DesktopShell apps={apps} /></div>;
}

AnatomyCopy Anchor Link

DesktopShell                    data-slot="desktop-shell"
├─ wallpaper                    a node or a token gradient
├─ DesktopMenuBar               app name, menus, start and end slots
├─ windows                      title bar, 8 resize handles, snap preview
├─ children                     desktop content behind the windows
├─ DesktopDock                  app icons, running dot, context-click actions
└─ DesktopLaunchpad             icon grid with search

APICopy Anchor Link

DesktopShellCopy Anchor Link

The pure window functions (openWindow, snapWindow, resizeRect and more) live in desktop-math.ts and are covered by node tests.

System menu: desktopPowerMenuCopy Anchor Link

A pure helper in desktop-power-menu.ts that builds the menu a desktop keeps at its leading corner. Pass it in menus, usually first.

const confirm = useConfirm(); // inside a <ConfirmProvider>
const system = desktopPowerMenu({
  appName: "ToGO",
  locale,
  onAbout, onSettings, onSleep, onRestart, onShutDown, onLogOut,
  confirm,
});

<DesktopShell apps={apps} menus={(focused) => [system, ...appMenus(focused)]} />;

Sleep, Restart and Shut Down start after a separator, and Log out starts its own group and is marked danger. Also exported: desktopPowerLabels, desktopPowerConfirm, DESKTOP_POWER_ACTIONS, DESKTOP_POWER_CONFIRMED.

ExamplesCopy Anchor Link

Control the list to persist it: keep windows in state and save it in onWindowsChange.

AccessibilityCopy Anchor Link

• The dock is a nav; icons are buttons with the app name, and a dot marks running apps.
• Window controls have labels; the title bar drags with the pointer and double-click maximises.
• The launchpad closes with Escape.

RTL & i18nCopy Anchor Link

Window x is measured from the inline start edge, so a saved layout mirrors in Arabic. Snap zones are "start" and "end", not left and right. Strings come from useOptionalNasaq() with a labels override.

Styling & tokensCopy Anchor Link

Only --nq-* tokens. Override the wallpaper with the wallpaper prop.

Do / Don'tCopy Anchor Link

• Do give each app a stable id.
• Do set single for apps that should have one window.
• Don't put a full page router inside a window without a fixed size.

RelatedCopy Anchor Link

Menubar, ContextMenu, Dialog, DesktopIconGrid.

LabCopy Anchor Link

Pages / App / Desktop OS Shell in the lab: Default, Arabic, Mobile, Power Menu, Power Menu Arabic.