@whiskeyjack-net/tauri

v0.4.3

Published

21 hours ago

Tauri-native app-shell layer for the Whiskeyjack design system: per-platform CSD window controls, OS accent integration, and desktop guards.

0High
0Medium
0Low

findingsimo

tauri tauri-v2 react window-controls desktop design-system updater csd

@whiskeyjack-net/tauri

The Tauri-native app-shell layer for the Whiskeyjack design system – the window-chrome pieces the DS itself stays free of, so the design system runs identically as a plain web app or inside a Tauri window.

This README documents the published artifact (@whiskeyjack-net/tauri, staged via npm run build:package). Inside the monorepo the workspace source export is @whiskeyjack/tauri.

Install

npm install @whiskeyjack-net/tauri

Peers: react/react-dom 18+, @tauri-apps/api 2+, react-i18next, @whiskeyjack-net/design-system (the updater UI uses Button/Toast), @phosphor-icons/react, and @tauri-apps/plugin-opener (optional – only for openExternal / the updater's download action). Everything is inert (guarded) off Tauri, so it is safe to ship in a plain web/PWA build.

Exports

Guards – isTauri(), isMobileTauri() (iPad-aware), isDesktopTauri(), isMacDesktop(), isLinuxDesktop(). The desktop shell must gate on desktop (mobile Tauri also sets __TAURI_INTERNALS__), or its desktop-only CSS leaks onto phones. isLinuxDesktop() is the guard for the transparent-window platform – Linux windows are undecorated with CSS-rounded corners, so anything that would make the canvas opaque (notably the DS useTheme's root paint – pass paintRoot: !isLinuxDesktop()) has to gate on it. Android's user agent also says "Linux", which is why the guard excludes mobile rather than testing the UA alone.
WindowControlsLeft / WindowControlsRight – CSD window-control buttons, rendering the exact per-side buttons the backend reports (data-wc-left / data-wc-right on <html>), so the app matches each desktop's convention. Mount them in the DS AppHeader's chrome slot.
useSystemAccent() – on Tauri desktop, reads the OS accent color and overrides the DS --color-accent-* variables, adds the .tauri-desktop / .tauri-platform-* markers, and publishes the --wc-left/right-px window-control footprint the header-clearance CSS consumes. No-op elsewhere. It invokes two Rust commands (below); without them it falls back to the platform default and warns once in development.
useWindowDrag() – returns { onMouseDown } to spread onto whatever should behave like a title bar, usually the DS AppHeader. Drags the window, zooms on double-click, skips interactive descendants so the nav keeps its clicks, and pre-caches the window module so the first drag does not stick. Inert outside Tauri desktop, so one Layout serves the web build too.
@whiskeyjack-net/tauri/css/window-controls – the window-control CSS (import once); pairs with the components and the AppHeader chrome/rowClassName extension points.
openExternal(url) – open a URL in the system browser on Tauri (via the opener plugin), a new tab on the web.
In-app updater (direct-download desktop builds) – createUpdater(config) binds the checker to one app's release channel; pair it with the UI:
- createUpdater({ repo, tagPrefix, fallbackVersion }) → { getAppVersion, checkForUpdates }. Polls the GitHub repo's releases, matches tagPrefix, compares semver, and resolves the best installer asset for the platform. fallbackVersion is the web/PWA version (under Tauri the runtime reports it).
- <UpdateBanner version releaseUrl onDismiss /> – a floating DS Toast surfaced on launch when a newer release exists.
- <UpdateDialog updater onClose /> – a "check for updates" body for a DS BottomDrawer (Settings). Auto-runs the check on open.
Store-distributed builds (App Store, Snap, ...) update through the store – gate the checker off for those.
The updater UI reads these translation keys from the app's locales: update.available ({{version}}), update.download, update.later, update.checking, update.currentVersion ({{version}}), update.upToDate, update.error, common.cancel; the window controls read window.close / window.minimize / window.maximize.

Capabilities this pack needs

Tauri v2 gates each window command behind its own capability, and core:default covers fewer of them than the name suggests. Anything missing here fails as a rejected promise at the moment of use, which looks like a control that quietly does nothing.

// src-tauri/capabilities/default.json
{
  "permissions": [
    "core:default",
    "core:window:allow-start-dragging",   // useWindowDrag
    "core:window:allow-toggle-maximize",  // useWindowDrag, double-click to zoom
    "core:window:allow-minimize",         // WindowControls (Windows / Linux)
    "core:window:allow-close"             // WindowControls (Windows / Linux)
  ]
}

The first two are needed on every desktop platform including macOS. The last two matter where the app draws its own buttons rather than deferring to native ones, so a macOS-only build can skip them until it does not.

Missing capabilities now warn once in development, naming the one to add.

The two commands `useSystemAccent` expects

The Rust side is yours (see below), and these two are the part the pack actually calls. Neither is required for a correct window – missing ones fall back to the platform default and warn once in development – but implementing them is what makes the OS accent and the per-desktop Linux button layout work.

| Command | Returns | Without it | |---|---|---| | get_window_controls_layout | { left: string[], right: string[], native: bool } | macOS assumes native traffic lights, Windows and Linux assume a right-hand minimize, maximize, close. Only Linux genuinely loses something: its layout is a per-desktop setting that only the backend can read. | | get_system_accent_color | Option<String>, #rrggbb | The app keeps its own theme accent. |

macOS needs only this much:

#[derive(serde::Serialize)]
pub struct WindowControlsLayout { left: Vec<String>, right: Vec<String>, native: bool }

#[tauri::command]
pub fn get_window_controls_layout() -> WindowControlsLayout {
    WindowControlsLayout { left: vec![], right: vec![], native: true }
}

Register it in invoke_handler!. Chip Away's src-tauri/src/window_controls.rs is the full version, including reading GNOME and Pantheon button layouts.

Before the fallback existed, an app that skipped these got no .tauri-controls-* class, so .tauri-pad-controls resolved to zero padding and the header sat underneath the macOS traffic lights, with nothing logged anywhere. That is the failure the defaults and the dev warning replace.

Not included (by design)

The Rust side (src-tauri/: the two commands above, tray/menus, notifications) is an owned scaffold template, seeded from a reference app – not an npm library.
Auth/sync is app-coupled (Firebase) and lives in the app or a future starter kit.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@whiskeyjack-net/tauri

Install

Exports

Capabilities this pack needs

The two commands useSystemAccent expects

Not included (by design)

License

The two commands `useSystemAccent` expects