WindowPane

Anything at all, drawn the way one of four operating systems draws a window. The title bar drags, the corners resize and the three buttons are real buttons, so a screenshot, a demo or a piece of a landing page can be shown as the thing it will be rather than as a picture of it.

import { WindowPane } from 'neba';

<WindowPane os="macos" title="Notes" width={520} height={320}>
  <Editor />
</WindowPane>;

It is not a real window: there is no desktop, no z-order and nothing outside the page. What it draws is the frame, and what it holds is yours.

Props

Prop	Type	Default	Description
os	'macos' | 'macosx' | 'windows11' | 'windows10' | 'windows8' | 'windows7' | 'windowsxp' | 'linux'	'macos'	Whose window this is a picture of. Decides where the controls sit and how they are drawn, how tall the title bar is and what colour, and how thick the frame is and how its corners are cut. A version is its own entry wherever the title bar is what changed: XP painted it Luna blue and framed the window in it, 7 made it glass, 8 threw both away, 10 ruled it off from the body, 11 rounded the corners, and macosx is Aqua
title	ReactNode	—	The window’s name, in the title bar. Also what names the window itself
icon	ReactNode	—	A glyph beside the title: the app’s mark
actions	ReactNode	—	Anything else the title bar carries, set beside the controls
controls	boolean | ('minimize' | 'maximize' | 'close')[]	true	Which of the three buttons the title bar has. The order is the system’s rather than the array’s: macOS puts close first and Windows puts it last
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The scale of the chrome: the title bar’s height, its buttons and its type. It does not touch the content
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	The colour family the focus rings and an accent title bar take
accent	boolean	false	Dyes the title bar with the colour family, the way Windows offers to
transparency	number	0	From 0 to 1. It applies to the title bar, the body’s own fill and the border: never to the content. Anything above 0 also turns the acrylic on
active	boolean	—	Whether this is the window in front. Left out, the window works it out for itself: it is in front until another WindowPane on the page is pressed or takes the focus, and a press on the page *around* the windows changes nothing. A window behind keeps its shape and loses its emphasis(grey traffic lights, no accent, one step less shadow) never its opacity
elevationshared	0 | 1 | 2 | 3	2	The shadow around the window. 0 means no shadow at all
positionshared	'static' | 'absolute' | 'fixed'	'static'	How the window is laid out. static leaves it in the flow (as a relatively positioned box, so offset moves nothing around it), absolute pins it inside the nearest positioned ancestor, fixed pins it to the viewport
draggable	boolean	false	Lets the title bar be dragged
resizable	boolean	false	Lets the edges and corners be dragged
width	number | string	—	The window’s width
height	number | string	—	And its height. Left out, the window is as tall as what is in it
minWidth	number	180	How small it may be dragged, in pixels
minHeight	number	—	The same downward. Defaults to the title bar’s own height
offset	{ x: number; y: number }	—	How far it has been dragged from where the layout put it
defaultOffset	{ x: number; y: number }	{ x: 0, y: 0 }	Where an uncontrolled window starts
onOffsetChange	(offset: { x: number; y: number }) => void	—	Called while the window is dragged
onResize	(size: { width: number; height: number }) => void	—	Fires with the window’s size, in pixels, while an edge is dragged
open	boolean	—	Whether the window is on screen at all. Closing it renders nothing
defaultOpen	boolean	true	Where an uncontrolled window starts
onOpenChange	(open: boolean) => void	—	Called when the close button is pressed
minimized	boolean	—	Whether the window is rolled up to its title bar. A page has no dock to send it to, so this is what minimizing means
defaultMinimized	boolean	false	Where an uncontrolled window starts
onMinimizedChange	(minimized: boolean) => void	—	Called when the minimize button is pressed
maximized	boolean	—	Whether the window fills whatever is holding it. Its corners go square while it does
defaultMaximized	boolean	false	Where an uncontrolled window starts
onMaximizedChange	(maximized: boolean) => void	—	Called when the maximize button is pressed, and on a double click of the title bar
scroll	boolean	true	Whether content taller than the window scrolls
locale	string	—	Which language the title bar’s buttons name themselves in: a BCP 47 tag
minimizeLabel	string	—	The minimize button’s own name
maximizeLabel	string	—	The maximize button’s own name
restoreLabel	string	—	And what that button is called while the window is maximized
closeLabel	string	—	The close button’s own name
resizeLabel	string	—	The name of the corner a keyboard resizes with
render	useRender.RenderProp	—	Renders something other than a div (render={<section />})
children	ReactNode	—	What is in the window

Every other <div> attribute passes through to the root, except title (here it is the window's name and a ReactNode), and onResize, which reports pixels rather than a DOM event. The shared axes (size color elevation position) are defined in prop conventions.

Examples

os

Eight systems, and a version is its own entry wherever the title bar is what changed:

os	What it draws
macos	Three coloured dots on the left, the title centred over the whole window, one flat sheet
macosx	Aqua: a short striped bar, glossy lights, a bold embossed title, square bottom corners
windows11	Three rectangles hard against a rounded top-right corner, bar and body one Mica sheet
windows10	The same three over square corners, a shorter bar, and a rule under it
windows8	Flat and square, no rule, and a band of colour around the whole window
windows7	Aero: a sheet of glass with the content sunk into it, the page blurred through the band as well as the caption, a glowing title and a wider close
windowsxp	Luna: the glossy blue caption curve, a band of the same blue down the sides and along the bottom, coloured button plates
linux	A GNOME header bar: taller, with circular buttons and a centred title

The older systems paint their own chrome rather than the page's, so Luna stays blue and Aqua stays grey on a page switched to dark: the same choice Mockup's finishes make, because hardware and system chrome are not the theme.

XP and Aero are also the two that have a band rather than a hairline: the content is sunk into a stretch of the system's own material down both sides and along the bottom, which is most of what makes either of them recognisable. accent dyes the band with the caption, so a window in your own colour is framed in it too.

The buttons carry no other party's marks (a minimize is a line, a maximize is a box, a close is a cross), and none of the chrome writes a word except the title you gave it.

import { Typography, WindowPane } from 'neba';
import type { NebaWindowOs } from 'neba';

const systems: { os: NebaWindowOs; title: string; note: string }[] = [
  { os: 'macos', title: 'Finder', note: 'Traffic lights, centred title, Mica-flat bar' },
  { os: 'macosx', title: 'Finder', note: 'Aqua: striped bar, glossy lights, square feet' },
  { os: 'windows11', title: 'Explorer', note: 'Rounded corners, one sheet, no rule' },
  { os: 'windows10', title: 'Explorer', note: 'Square corners, white bar, ruled off' },
  { os: 'windows8', title: 'Explorer', note: 'Flat, and a band of colour round the edge' },
  { os: 'windows7', title: 'Explorer', note: 'Aero glass, glowing title, wider close' },
  { os: 'windowsxp', title: 'Explorer', note: 'Luna blue, framed, coloured plates' },
  { os: 'linux', title: 'Files', note: 'A header bar, taller, with circles' }
];

export default function WindowPaneOs() {
  return (
    <div className="grid w-full gap-6 sm:grid-cols-2">
      {systems.map(({ os, title, note }) => (
        <WindowPane key={os} os={os} title={title} height={130} active={os === 'macos'}>
          <div className="flex h-full flex-col gap-1 p-3">
            <Typography level="caption">os=&quot;{os}&quot;</Typography>
            <Typography level="caption" color="secondary">
              {note}
            </Typography>
          </div>
        </WindowPane>
      ))}
    </div>
  );
}

controls

true is all three buttons, false is none, and an array is exactly the ones named. The order is the system's rather than the array's, so ['close', 'minimize'] still puts close last on Windows.

Each one is a controlled/uncontrolled pair: open, minimized and maximized, each with a default* and an on*Change. Closing an uncontrolled window renders nothing; minimizing rolls it up to its title bar, because a page has no dock to send it to; maximizing fills whatever is holding the window, which is the nearest positioned ancestor with position="absolute" and the viewport with fixed. A double click on the title bar maximizes too.

import { useState } from 'react';
import { Button, Typography, WindowPane } from 'neba';

export default function WindowPaneControls() {
  const [open, setOpen] = useState(true);
  const [minimized, setMinimized] = useState(false);
  const [maximized, setMaximized] = useState(false);

  return (
    <div className="flex w-full flex-col items-center gap-4">
      {/* The stage a maximized window fills. Anything positioned is enough. */}
      <div className="relative h-64 w-full overflow-hidden rounded-(--neba-radius-md) bg-(--neba-primary-soft) p-4">
        {open ? (
          <WindowPane
            os="windows11"
            title="Terminal"
            position="absolute"
            width={320}
            height={180}
            offset={{ x: 24, y: 24 }}
            open={open}
            onOpenChange={setOpen}
            minimized={minimized}
            onMinimizedChange={setMinimized}
            maximized={maximized}
            onMaximizedChange={setMaximized}
          >
            <div className="p-3 font-mono">
              <Typography level="body">$ npm install neba</Typography>
              <Typography level="body" color="secondary">
                added 1 package in 1.2s
              </Typography>
            </div>
          </WindowPane>
        ) : null}
      </div>

      <div className="flex gap-2">
        <Button size="sm" variant="outline" onClick={() => setOpen(true)} disabled={open}>
          Reopen
        </Button>
        <Button
          size="sm"
          variant="outline"
          onClick={() => setMinimized(false)}
          disabled={!minimized}
        >
          Unroll
        </Button>
      </div>
    </div>
  );
}

draggable and resizable

draggable moves the window on left and top (never a transform, so no glyph is resampled for the length of the drag), and reports where it went through onOffsetChange. resizable puts a handle on all four edges and all four corners; minWidth and minHeight bound them, and onResize fires with the pixel size as they move.

Both need somewhere to move: give the window position="absolute" and a positioned ancestor, or position="fixed".

import { Typography, WindowPane } from 'neba';

export default function WindowPaneInteractive() {
  return (
    <div className="relative h-80 w-full overflow-hidden rounded-(--neba-radius-md) bg-(--neba-secondary-soft)">
      <WindowPane
        title="Inspector"
        position="absolute"
        draggable
        resizable
        width={260}
        height={170}
        defaultOffset={{ x: 20, y: 20 }}
      >
        <div className="p-3">
          <Typography level="body">Drag the title bar.</Typography>
          <Typography level="caption" color="secondary">
            Pull any edge or corner to resize.
          </Typography>
        </div>
      </WindowPane>

      <WindowPane
        os="linux"
        title="Console"
        position="absolute"
        draggable
        resizable
        width={230}
        height={150}
        defaultOffset={{ x: 210, y: 130 }}
      >
        <div className="p-3">
          <Typography level="caption" color="secondary">
            Press one: the other steps back.
          </Typography>
        </div>
      </WindowPane>
    </div>
  );
}

Which window is in front

Left out, active looks after itself: a window is in front until another WindowPane on the page is pressed or takes the focus. A press on the page around the windows changes nothing: a paragraph is not a desktop.

Being in front is drawn the way each system draws it: coloured traffic lights against grey ones on macOS, an accent title bar and an accent border on Windows 10, a tinted header bar on GNOME. And, on all four, one step more shadow than the windows behind it. Pass active to drive that yourself, which is what a caller keeping its own z-order wants.

Motion

Maximizing, restoring and rolling up are journeys between two geometries, so the window travels rather than jumps: left, top, width and height are what move, never a transform, so no glyph in the window is resampled on the way. A window that was never given a height is measured and pinned for the length of the roll-up, because auto is not a length a transition can start from.

A rolled-up window keeps its body in the tree, inert and clipped, which is what the roll-up travels over. A closed one fades before it goes rather than stopping existing. Every one of these is instant for a reader who has asked for reduced motion.

accent, transparency, active

accent dyes the title bar with color, the way Windows offers to, and on windows10 it takes the window's border with it, which is what that version does. transparency is how much of the page shows through the chrome, from 0 to 1; it applies to the title bar, the body's own fill and the border, never to the content on them, and anything above 0 also turns the acrylic on so what is behind is blurred rather than merely visible. active={false} pins the window behind whatever else is on the page.

import { Typography, WindowPane } from 'neba';

export default function WindowPaneAppearance() {
  return (
    <div className="grid w-full gap-6 sm:grid-cols-2">
      <WindowPane os="windows10" title="Accent" accent color="primary" height={120}>
        <div className="p-3">
          <Typography level="caption" color="secondary">
            accent · color=&quot;primary&quot;
          </Typography>
        </div>
      </WindowPane>

      <WindowPane os="macos" title="Translucent" transparency={0.45} height={120}>
        <div className="p-3">
          <Typography level="caption" color="secondary">
            transparency=&#123;0.45&#125;
          </Typography>
        </div>
      </WindowPane>

      <WindowPane os="macos" title="Flat" elevation={0} height={120}>
        <div className="p-3">
          <Typography level="caption" color="secondary">
            elevation=&#123;0&#125;
          </Typography>
        </div>
      </WindowPane>

      <WindowPane os="linux" title="Behind" active={false} height={120}>
        <div className="p-3">
          <Typography level="caption" color="secondary">
            active=&#123;false&#125;
          </Typography>
        </div>
      </WindowPane>
    </div>
  );
}

Accessibility

• The root is a role="group" labelled by its own title, so a screen reader reads the window's name before its contents.
• The three title bar buttons are real <button>s with names from locale, and the maximize one renames itself to "Restore" while the window is maximized.
• One resize handle (the bottom-right corner) is reachable from the keyboard and resizes with the arrow keys. The other seven are pointer affordances and are hidden from the accessibility tree; a keyboard reader has the same range through maximize.
• Dragging is a pointer affordance as well. A window that must be movable without one should be given its offset by the caller.