@spartan-native/desktop-ui 0.2.0 → 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 CHANGED
@@ -30,14 +30,15 @@ Import groups: `SnDesktopUiImports` (everything), `SnWindowImports`, `SnControls
30
30
 
31
31
  | Element | Use it for | Key API |
32
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`; 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 | section: `title`; item: `active`, `icon`, `badge` |
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
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
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>` |
37
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 |
38
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 |
39
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]` |
40
- | `<sn-inspector-layout>` > `<sn-inspector>` > `<sn-inspector-section>` > `<sn-inspector-property>` | A details/properties side panel | inspector: `[(open)]`, `title` (required), `icon`; section: `title`; property: `label` (required) |
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` |
41
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"` |
42
43
 
43
44
  ### Controls spartan doesn't have
@@ -47,6 +48,8 @@ Import groups: `SnDesktopUiImports` (everything), `SnWindowImports`, `SnControls
47
48
  | `<sn-split-button>` + `ng-template[snSplitButtonMenu]` | `label` (required), `icon`, `variant: 'standard' \| 'accent'`, `small`, `disabled`, `menuLabel`; `(triggered)` |
48
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` |
49
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 |
50
53
  | `<sn-tree>` + `<sn-tree-item>` | tree: `[(selection)]`, `multiple`, `(activated)`; item: `value`, `label` (required), `icon`, `[(expanded)]`, `expandable`; nest items for children; slot `[snTreeItemEnd]` |
51
54
 
52
55
  ### Menus
@@ -93,7 +96,8 @@ const menu: SnMenuItem[] = [
93
96
  1. **Never write OS shortcuts or OS names by hand** ("Ctrl+S", "⌘S"). Use `snShortcut` or `formatShortcut()`.
94
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.
95
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.
96
- 4. **Mark dialog buttons**: `snSheetPrimary` / `snSheetCancel` / `snSheetSecondary` in `sn-modal-sheet`, and helm's `snDefaultAction` / `snCancelAction` in spartan dialogs.
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.
97
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.
98
101
  6. They support Windows contrast themes (`forced-colors`) already. Don't add colors that break that, such as backgrounds without a border.
99
- 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, so they keep the bar's icon-only mode, overflow and arrow-key navigation.
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.