@spartan-native/desktop-ui 0.0.0-stage → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +103 -0
- package/LICENSE +21 -0
- package/README.md +98 -2
- package/fesm2022/spartan-native-desktop-ui.mjs +8020 -0
- package/fesm2022/spartan-native-desktop-ui.mjs.map +1 -0
- package/package.json +48 -3
- package/types/spartan-native-desktop-ui.d.ts +2223 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# AGENTS.md: @spartan-native/desktop-ui
|
|
2
|
+
|
|
3
|
+
Instructions for AI coding agents building an Angular app with `@spartan-native/desktop-ui`.
|
|
4
|
+
|
|
5
|
+
## What this package is
|
|
6
|
+
|
|
7
|
+
Layer 03 of Spartan Native (optional). These are the pieces stock spartan/ui doesn't have: **window chrome**, the **patterns each OS is known for**, **menus**, and the **desktop controls** spartan lacks. Each component changes its _layout_ per OS, not just its colors, and follows the skin live.
|
|
8
|
+
|
|
9
|
+
It requires `@spartan-native/theme` (with `provideSpartanNative()`) and `@spartan-native/helm`. Its styles are component-scoped, so there is no extra stylesheet to load. Icon inputs (`icon="lucideClock"`) take an `@ng-icons` name you've registered with `provideIcons()`.
|
|
10
|
+
|
|
11
|
+
**Before building something yourself, check this list.** If an OS pattern below fits, use it instead of composing spartan cards and buttons by hand.
|
|
12
|
+
|
|
13
|
+
## Components (`import … from '@spartan-native/desktop-ui'`)
|
|
14
|
+
|
|
15
|
+
Import groups: `SnDesktopUiImports` (everything), `SnWindowImports`, `SnControlsImports`, `SnMenuImports`, `SnSettingsImports`, `SnPlatformImports`, `SnCommandBarImports`, `SnCoachMarkImports`, `SnInspectorImports`, `SnSidebarNavImports`, `SnSplitButtonImports`, `SnTreeImports`, `SnStatusBarImports`, `SnAssistantImports`, `SnChecklistImports`, or the single classes `SnModalSheet`, `SnStatusPage`, `SnNumberBox` and `SnTooltip`.
|
|
16
|
+
|
|
17
|
+
### Window chrome
|
|
18
|
+
|
|
19
|
+
| Element | Inputs / outputs | Slots |
|
|
20
|
+
| --- | --- | --- |
|
|
21
|
+
| `<sn-title-bar>` | `title`, `subtitle`, `windowControls: 'custom' \| 'native'`, `buttons`, `maximized`; `(minimize)` `(maximize)` `(close)` | `[snTitleBarIcon]`, `[snTitleBarStart]`, `[snTitleBarEnd]` |
|
|
22
|
+
| `<sn-window-controls>` | `buttons`, `maximized`, `linuxAll`, `nativeActions` (default `true`: calls the host's window); same outputs | none |
|
|
23
|
+
| `<sn-status-bar>` + `[snStatusItem]` | `ariaLabel`; item: `live` (announces changes) | `[snStatusBarEnd]` |
|
|
24
|
+
|
|
25
|
+
- The title bar is already a drag region for Electron, Wails and Tauri. Don't add your own `app-region` or `--wails-draggable`.
|
|
26
|
+
- With a host that owns the window (`wailsHost()`), the window buttons minimize, maximize and close the real window by themselves.
|
|
27
|
+
- Use `windowControls="native"` when the OS draws the buttons itself (Electron `titleBarOverlay`, PWA Window Controls Overlay, a macOS hidden-inset or overlay title bar). The bar leaves room for them where the **real** OS draws them, so a Mac dressed as another skin keeps the space for its traffic lights.
|
|
28
|
+
|
|
29
|
+
### OS patterns
|
|
30
|
+
|
|
31
|
+
| Element | Use it for | Key API |
|
|
32
|
+
| --- | --- | --- |
|
|
33
|
+
| `<sn-command-bar>` + `button[snCommand]` + `<sn-command-group>` | A toolbar of commands (Windows CommandBar, macOS toolbar, GNOME header bar) | bar: `title` (a heading; `headingLevel`, default 1), `titlePosition: 'auto' \| 'start' \| 'center'`, `commands` (a `TemplateRef` of commands declared elsewhere, e.g. by the page), `overflowItems: SnMenuItem[]`, `collapse: 'auto' \| 'none'`, `ariaLabel`, `overflowLabel`; page commands: `<ng-template snPageCommands>` in a page, `[commands]="inject(SnPageCommands).template()"` on the shell's bar; command: `label` (required), `icon`, `disabled`, `hideLabel`, `variant: 'default' \| 'accent'`, `priority` (lower collapses first), `secondary` (always in the overflow menu); group: `label`; slots `[snCommandBarStart]`, `[snCommandBarEnd]`, and `ng-template[snCommandOverflow]` (your own overflow menu, used only while nothing has collapsed) |
|
|
34
|
+
| `<sn-sidebar-nav>` > `<sn-sidebar-section>` > `a[snSidebarItem]` | App navigation | nav: `collapsed` (icons only; labels become tooltips, badges a mark on the icon; items without an `icon` keep their short content); section: `title`; item: `active`, `icon`, `badge`, `tooltip` (what the collapsed tooltip says; default the item's text). Items are styled by their `sn-sidebar-item` class, so an item can also be a spartan menu trigger |
|
|
35
|
+
| `<sn-settings-group>` + `<sn-settings-row>` | Settings and preferences screens | group: `title`, `description`; row: `title` (required), `subtitle`; slot `[snSettingsIcon]`; the control goes in the row's content |
|
|
36
|
+
| `<sn-status-page>` | Empty, error and "nothing here" states | `icon`, `title` (required), `description`; content = actions |
|
|
37
|
+
| `SnAlert` (service) | Alerts and confirmations: the host's native alert where it has one, else an in-page `alertdialog` sheet | `show(options: MessageOptions): Promise<string \| null>` (the pressed button's id; `cancelId` on Esc), `confirm(message, { title?, kind?, confirmLabel?, cancelLabel? }): Promise<boolean>` |
|
|
38
|
+
| `<sn-modal-sheet>` | A modal form (macOS sheet, ContentDialog, AdwDialog, …) | `[(open)]`, `title` (required), `role`; buttons `[snSheetCancel]`, `[snSheetPrimary]`, and `[snSheetSecondary]` for a third button that doesn't close the sheet (Back, Don't Save); put `snSheetHost` on the window frame so the macOS sheet hangs from the title bar |
|
|
39
|
+
| `<sn-assistant>` + `ng-template[snAssistantPage]` | A step-by-step setup flow (Windows wizard, macOS Setup Assistant, GNOME pages with dots, KDE QWizard) | `[(step)]`, `cancelable`, `backLabel`, `nextLabel`, `finishLabel`, `cancelLabel`, `progressLabel`; `(finish)`, `(cancel)`; page: `title` (required), `canContinue`. Put it in an `sn-modal-sheet` without sheet buttons for a modal assistant |
|
|
40
|
+
| `<sn-checklist>` + `<sn-checklist-item>` | A get-started list of setup tasks that tick off | item: `title` (required), `done`, `keepAction`, `doneLabel`, `todoLabel`; content = description; slot `[snChecklistAction]` |
|
|
41
|
+
| `<sn-inspector-layout>` > `<sn-inspector>` > `<sn-inspector-section>` > `<sn-inspector-property>` | A details/properties side panel | inspector: `[(open)]` (`openChange` fires only when the user closes it), `title` (required), `icon`; section: `title`; property: `label` (required). Resizable with `snResizable` |
|
|
42
|
+
| `<sn-coach-mark>` + `[snCoachMarkFor]` | Teaching tips and onboarding callouts anchored to a control | `title` (required), `icon`, `placement`, `[(open)]`, `closeLabel`; slots `[snCoachMarkHero]`, `[snCoachMarkAction]` (secondary first, primary last); anchor: `[snCoachMarkFor]="tip"` |
|
|
43
|
+
|
|
44
|
+
### Controls spartan doesn't have
|
|
45
|
+
|
|
46
|
+
| Element | Key API |
|
|
47
|
+
| --- | --- |
|
|
48
|
+
| `<sn-split-button>` + `ng-template[snSplitButtonMenu]` | `label` (required), `icon`, `variant: 'standard' \| 'accent'`, `small`, `disabled`, `menuLabel`; `(triggered)` |
|
|
49
|
+
| `<sn-number-box>` | `[(value)]` or `formControl` / `ngModel` (it's a ControlValueAccessor), `min`, `max`, `step`, `largeStep`, `decimals`, `spinButtons`, `acceptsExpression` (`2*8+1`), `disabled`, `placeholder`, `ariaLabel` |
|
|
50
|
+
| `[snTooltip]` | `snTooltip` (the text), `snTooltipDisabled`. The skin's own tooltip on hover and keyboard focus; visual only, so give the element its own accessible name |
|
|
51
|
+
| `<sn-search-field>` | `[(value)]` or `formControl` / `ngModel`, `placeholder` (default "Search", also the accessible name), `label`, `clearLabel`, `disabled`; `(submitted)` on Enter; `focus()`, `clear()`. Esc empties a filled field and stops there; on an empty field it reaches the dialog |
|
|
52
|
+
| `[snResizable]` | On `<sn-sidebar-nav>`, `<sn-inspector>` or any side panel: drag the inner edge to resize, double-click to reset, ← → / Home / End from the keyboard. `snResizable` (storage key; empty: not remembered), `resizeEdge: 'auto' \| 'start' \| 'end'`, `resizeRatio` (default 0.2 of the parent), `resizeMin` (px, default 192), `resizeMaxRatio` (default 0.5), `resizeDisabled` (e.g. while the sidebar is collapsed), `resizeLabel`. The width is a share of the parent, so it follows the window |
|
|
53
|
+
| `<sn-tree>` + `<sn-tree-item>` | tree: `[(selection)]`, `multiple`, `(activated)`; item: `value`, `label` (required), `icon`, `[(expanded)]`, `expandable`; nest items for children; slot `[snTreeItemEnd]` |
|
|
54
|
+
|
|
55
|
+
### Menus
|
|
56
|
+
|
|
57
|
+
One `SnMenuItem[]` definition feeds both the menu bar and context menus. With a host that has native menus, they're the OS's own (the macOS global menu bar, OS context menus). Otherwise they're drawn in the page with the skin's menu styles.
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
const menu: SnMenuItem[] = [
|
|
61
|
+
{ role: 'appMenu' }, // macOS only; dropped elsewhere
|
|
62
|
+
{
|
|
63
|
+
label: 'File',
|
|
64
|
+
submenu: [
|
|
65
|
+
{ label: 'New backup…', accelerator: 'mod+n', action: () => this.create() },
|
|
66
|
+
{ type: 'separator' },
|
|
67
|
+
{ role: 'close' },
|
|
68
|
+
],
|
|
69
|
+
},
|
|
70
|
+
{ role: 'editMenu' },
|
|
71
|
+
];
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
```html
|
|
75
|
+
<sn-menubar [menu]="menu" />
|
|
76
|
+
<!-- native: 'auto' | 'always' | 'never' -->
|
|
77
|
+
<li [snContextMenu]="fileMenu(file)">{{ file.name }}</li>
|
|
78
|
+
<!-- snContextMenuNative, snContextMenuDisabled -->
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
- `SnMenuItem` is the contract's `MenuItem` (`id`, `label`, `type` normal/checkbox/radio/separator, `accelerator`, `enabled`, `checked`, `role`, `submenu`) plus an `action` function.
|
|
82
|
+
- Write accelerators in the portable notation: `mod+shift+s`, `alt+f4`, `delete`, `f2`. `mod` is ⌘ on macOS and Ctrl elsewhere.
|
|
83
|
+
- The menu bar binds its accelerators. Context menus only _show_ them, so bind those shortcuts where the selection lives.
|
|
84
|
+
- For menus built in code, use the `SnNativeMenus` service. Helpers: `toHostMenu()`, `tidyMenu()`, `inPageMenu()`, `matchesAccelerator()`, `runEditCommand()`.
|
|
85
|
+
|
|
86
|
+
### Platform helpers
|
|
87
|
+
|
|
88
|
+
| API | Use |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| `<kbd snShortcut="mod+shift+s">` | Shows a shortcut the OS's way (`⇧⌘S` or `Ctrl+Shift+S`). Follows the **real** OS (the keyboard), not the skin |
|
|
91
|
+
| `formatShortcut(shortcut, family)` | The same, in code |
|
|
92
|
+
| `*snPlatformIf="'macos'; else other"` | Renders per skin (`'mac'`, `'qt'`, …), per family (`'windows'`, `'macos'`, `'linux'`, `'chromeos'`, `'web'`) or for a list of them; updates live |
|
|
93
|
+
|
|
94
|
+
## Rules
|
|
95
|
+
|
|
96
|
+
1. **Never write OS shortcuts or OS names by hand** ("Ctrl+S", "⌘S"). Use `snShortcut` or `formatShortcut()`.
|
|
97
|
+
2. **Don't branch on the user agent.** Use `*snPlatformIf` or `injectSkin()` for the look, and `injectPlatformFamily()` (from the theme) for behavior that follows the real OS: the keyboard, where the OS draws window buttons. The menu bar, context menus and `snShortcut` already do.
|
|
98
|
+
3. **Use these components for the window frame.** A typical shell is `<div class="sn-window" snSheetHost>`, then `<sn-title-bar>`, then `<sn-sidebar-nav class="sn-sidebar">` beside `<main class="sn-content">`, with `<sn-status-bar>` at the bottom.
|
|
99
|
+
4. **Mark dialog buttons**: `snSheetPrimary` / `snSheetCancel` / `snSheetSecondary` in `sn-modal-sheet`, and helm's `snDefaultAction` / `snCancelAction` in spartan dialogs. For a confirmation, call `SnAlert.confirm()` instead of building both the native alert and its in-page fallback.
|
|
100
|
+
5. Don't restyle these components per OS from app code. They read the theme's tokens, and every host element carries `data-family` and `data-skin` if you really need a hook.
|
|
101
|
+
6. They support Windows contrast themes (`forced-colors`) already. Don't add colors that break that, such as backgrounds without a border.
|
|
102
|
+
7. **Command bars:** give each command a `priority` when some matter more, mark rarely used ones `secondary`, and use `<sn-command-group>` instead of styling your own capsules or dividers. Commands a page owns go through the bar's `[commands]` template (`<ng-template snPageCommands>` + `SnPageCommands` do the plumbing), so they keep the bar's icon-only mode, overflow and arrow-key navigation.
|
|
103
|
+
8. **Side panels:** make sidebars and inspectors resizable with `snResizable` instead of a hand-written drag handle, and fold the sidebar with `collapsed` instead of overriding its item styles.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Roland Molnár
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,99 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @spartan-native/desktop-ui
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Layer 03 · optional.** The pieces stock spartan doesn't have: **window chrome** and the **patterns each OS is known for**. Each component changes its _layout_ per OS, not just its colors, and follows the skin live.
|
|
4
|
+
|
|
5
|
+
> Status: **implemented for all seven skins** (Windows 11 and 10, macOS 26 and 13–15, GNOME, KDE Plasma, ChromeOS): title bar, window controls, status bar, the six OS patterns (command bar, coach mark, modal sheet, inspector, settings list, status page), an assistant and a setup checklist, sidebar navigation, a skinned tooltip, the desktop controls spartan lacks (split button, number box, tree view), shortcut formatting and `*snPlatformIf`, and the menubar adapter with context menus (native through the host, in the page otherwise). Every component also follows Windows contrast themes (`forced-colors`). Spec: [`06-os-patterns.md`](https://github.com/Spartan-Native/spartan-native/blob/main/docs/06-os-patterns.md).
|
|
6
|
+
|
|
7
|
+
## Components
|
|
8
|
+
|
|
9
|
+
| Component | Windows 11 / 10 | macOS 26 / 13–15 | GNOME | KDE Plasma | ChromeOS |
|
|
10
|
+
| --- | --- | --- | --- | --- | --- |
|
|
11
|
+
| `<sn-title-bar>` | icon + title left, caption buttons right | traffic lights left, title centered | header bar, bold centered title | Breeze title bar | caption bar, round buttons |
|
|
12
|
+
| `<sn-window-controls>` | – □ × (close turns red) | ● ● ● (grey when inactive) | round × (all three with `linuxAll`) | Breeze glyph buttons | M3 round caption buttons |
|
|
13
|
+
| `<sn-status-bar>` + `[snStatusItem]` | Explorer status bar (10: ruled items) | Finder status bar, centered | GtkActionBar | Dolphin status bar | slim M3 footer |
|
|
14
|
+
| `<sn-command-bar>` | **CommandBar** | unified NSToolbar | AdwHeaderBar | KToolBar | top app bar |
|
|
15
|
+
| `<sn-coach-mark>` + `[snCoachMarkFor]` | **TeachingTip** | NSPopover | GtkPopover | Kirigami popup | rich tooltip |
|
|
16
|
+
| `<sn-modal-sheet>` | ContentDialog | **sheet** from the title bar | AdwDialog, buttons in the header bar | window-modal dialog | M3 dialog |
|
|
17
|
+
| `<sn-assistant>` | wizard: Step n of m, Back · Next · Cancel | Setup Assistant page, Go Back · Continue | pages with a header bar and dots | **QWizard** with the step list | M3 flow with dots |
|
|
18
|
+
| `<sn-checklist>` | numbered setup tasks that tick off, the same on every skin (accent tick) | | | | |
|
|
19
|
+
| `[snTooltip]` | Fluent ToolTip card | help tag | inverse bubble | framed tooltip | M3 plain tooltip |
|
|
20
|
+
| `<sn-inspector-layout>` + `<sn-inspector>` | SplitView pane | **Inspector** | AdwOverlaySplitView | Dolphin information panel | side sheet |
|
|
21
|
+
| `<sn-sidebar-nav>` | accent pill (10: 4px bar) | accent fill, grey when inactive | neutral rounded selection | accent-filled selection | tonal pill |
|
|
22
|
+
| `<sn-settings-group>` + `<sn-settings-row>` | SettingsCards (10: plain rows) | grouped Form section | **AdwPreferencesGroup** | Kirigami FormLayout | settings list in a tonal card |
|
|
23
|
+
| `<sn-status-page>` | Fluent empty state | ContentUnavailableView | **AdwStatusPage** | PlaceholderMessage | M3 empty state |
|
|
24
|
+
| `<sn-menubar>` | in-window menu bar | **global menu bar** with a native host; in-window otherwise | in-window menu bar | in-window menu bar | in-window menu bar |
|
|
25
|
+
| `[snContextMenu]` | OS context menu with a native host; otherwise the skin's menu at the pointer | | | | |
|
|
26
|
+
| `<sn-split-button>` | Fluent SplitButton | NSComboButton (split) | AdwSplitButton | QToolButton MenuButtonPopup | M3 split button |
|
|
27
|
+
| `<sn-number-box>` | NumberBox, inline ∧ ∨ | field + NSStepper | GtkSpinButton − + | QSpinBox, stacked arrows | M3 field with − + |
|
|
28
|
+
| `<sn-tree>` + `<sn-tree-item>` | TreeView, chevrons, accent pill | NSOutlineView, triangles | GtkTreeExpander list | Breeze QTreeView | Files app tree |
|
|
29
|
+
| `<kbd snShortcut="mod+shift+s">` | Ctrl+Shift+S | ⇧⌘S | Ctrl+Shift+S | Ctrl+Shift+S | Ctrl+Shift+S |
|
|
30
|
+
| `*snPlatformIf="'macos'; else other"` | renders per skin (`'mac'`) or family (`'macos'`, `'windows'`, `'linux'`) | | | | |
|
|
31
|
+
|
|
32
|
+
**Bold** marks the OS a pattern comes from. Each component has a docs page in Storybook (_Desktop UI_ → the component → _Docs_) with the per-OS table, live examples, usage, the full API and accessibility notes.
|
|
33
|
+
|
|
34
|
+
```html
|
|
35
|
+
<sn-title-bar title="Harbor Backup" subtitle="Office NAS" (close)="host.close()" (minimize)="host.minimize()">
|
|
36
|
+
<img snTitleBarIcon src="icon.svg" alt="" />
|
|
37
|
+
<button snTitleBarEnd hlmBtn variant="ghost" size="icon-sm" aria-label="Search">…</button>
|
|
38
|
+
</sn-title-bar>
|
|
39
|
+
|
|
40
|
+
<sn-settings-group title="Backups" description="Choose when and how backups run.">
|
|
41
|
+
<sn-settings-row title="Automatic backups" subtitle="Run in the background">
|
|
42
|
+
<ng-icon snSettingsIcon name="lucideClock" />
|
|
43
|
+
<hlm-switch [checked]="true" aria-label="Automatic backups" />
|
|
44
|
+
</sn-settings-row>
|
|
45
|
+
</sn-settings-group>
|
|
46
|
+
|
|
47
|
+
<sn-status-page
|
|
48
|
+
icon="lucideArchive"
|
|
49
|
+
title="No backups yet"
|
|
50
|
+
description="Add a destination to start protecting your files."
|
|
51
|
+
>
|
|
52
|
+
<button hlmBtn>Add destination</button>
|
|
53
|
+
</sn-status-page>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**Window integration:** the title bar is a drag region for Electron/Chromium (`app-region`), Wails (`--wails-draggable`) and Tauri (`data-tauri-drag-region`). Its buttons are excluded. `windowControls="native"` leaves room for buttons the OS draws itself (Electron `titleBarOverlay`, Window Controls Overlay). The buttons only emit `minimize` / `maximize` / `close`; a host adapter will wire them to the real window later.
|
|
57
|
+
|
|
58
|
+
**Inactive window:** the chrome carries `sn-chrome`, so the theme dims it, and the macOS lights turn grey.
|
|
59
|
+
|
|
60
|
+
**Borrowed skin styles:** the split button's parts carry the theme's button hook and the number box's field carries its text-field hook, so they are drawn by the skin's own button and field styles (every state included). Their sheets only lay the parts out.
|
|
61
|
+
|
|
62
|
+
**Contrast themes:** under `forced-colors: active`, selections and hovers use `Highlight` / `HighlightText`, and surfaces that were only outlined by a shadow (sheet, coach mark, settings cards, macOS lights) get a `CanvasText` edge.
|
|
63
|
+
|
|
64
|
+
## How it follows the OS
|
|
65
|
+
|
|
66
|
+
Every component reads `injectSkin()` from `@spartan-native/theme`: the theme service when `provideSpartanNative()` is present, otherwise the `data-sn-skin` attribute on `<html>`. Styles are component-scoped SCSS reading the theme's tokens, one block per family or skin (`:host([data-family='macos'])`, `:host([data-skin='qt'])`). Every host carries `data-slot`, `data-family` and `data-skin`. Sizes are in rem, so everything grows with the OS text size.
|
|
67
|
+
|
|
68
|
+
## Structure
|
|
69
|
+
|
|
70
|
+
| Path | Purpose |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `src/lib/window/` | `SnTitleBar`, `SnWindowControls`, `SnStatusBar` |
|
|
73
|
+
| `src/lib/patterns/` | `SnCommandBar`, `SnCommandGroup`, `SnCoachMark`, `SnModalSheet`, `SnAssistant`, `SnChecklist`, `SnInspector…`, `SnSidebarNav…`, `SnSettingsGroup`, `SnSettingsRow`, `SnStatusPage` |
|
|
74
|
+
| `src/lib/controls/` | `SnSplitButton`, `SnNumberBox`, `SnTree…`: desktop controls spartan doesn't have |
|
|
75
|
+
| `src/lib/platform/` | `formatShortcut()`, `SnShortcut`, `SnPlatformIf` |
|
|
76
|
+
| `src/lib/menubar/` | `SnMenubar`, `SnContextMenu`, `SnNativeMenus` and the menu model (`SnMenuItem`, `toHostMenu()`, `inPageMenu()`) |
|
|
77
|
+
| `src/stories/` | one stories file per component |
|
|
78
|
+
| `src/docs/` | one docs page (MDX) per component |
|
|
79
|
+
|
|
80
|
+
Imports: `SnWindowImports` (with the status bar), `SnControlsImports`, `SnMenuImports`, `SnSplitButtonImports`, `SnNumberBox`, `SnTreeImports`, `SnStatusBarImports`, `SnCommandBarImports`, `SnCoachMarkImports`, `SnModalSheet`, `SnAssistantImports`, `SnChecklistImports`, `SnTooltip`, `SnInspectorImports`, `SnSidebarNavImports`, `SnSettingsImports`, `SnStatusPage`, `SnPlatformImports`, or `SnDesktopUiImports` for everything.
|
|
81
|
+
|
|
82
|
+
## Dependencies
|
|
83
|
+
|
|
84
|
+
`@spartan-native/theme`, `@spartan-native/helm` (the tree view uses its selection model), `@ng-icons/core`, `@angular/cdk` (overlay, dialog, menu, a11y and bidi for the coach mark, modal sheet, command bar, split button and tree) and `@angular/forms` (the number box is a `ControlValueAccessor`), Angular `^22.2.0`. The stories also use stock spartan/ui (`@spartan-ng/helm/*`); the library itself doesn't.
|
|
85
|
+
|
|
86
|
+
**Menus:** `<sn-menubar>` and `[snContextMenu]` take one `SnMenuItem[]` definition. With a host that has native menus (`wailsHost()`), the macOS menu bar is the system's global one and context menus are the OS's; chosen items come back by id and run their `action`. Without one, both are drawn in the page with the theme's menubar and dropdown-menu hooks, and the menubar binds the accelerators.
|
|
87
|
+
|
|
88
|
+
## Next
|
|
89
|
+
|
|
90
|
+
Window effects and Snap Layouts through the host. See the [roadmap](https://github.com/Spartan-Native/spartan-native/blob/main/docs/09-roadmap.md).
|
|
91
|
+
|
|
92
|
+
## Commands
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
npm run storybook:desktop-ui # http://localhost:6008
|
|
96
|
+
npx ng test desktop-ui
|
|
97
|
+
npx ng build desktop-ui
|
|
98
|
+
npm run test:visual -- --project=desktop-ui # 511 screenshots: every story on all seven skins (+ dark)
|
|
99
|
+
```
|