@spartan-native/helm 0.0.0-stage → 0.2.0
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 +90 -0
- package/LICENSE +21 -0
- package/README.md +102 -2
- package/fesm2022/spartan-native-helm.mjs +691 -0
- package/fesm2022/spartan-native-helm.mjs.map +1 -0
- package/package.json +53 -3
- package/styles/_dialog-buttons.scss +50 -0
- package/styles/_selectable.scss +101 -0
- package/styles/spartan-native-helm.scss +14 -0
- package/types/spartan-native-helm.d.ts +234 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# AGENTS.md: @spartan-native/helm
|
|
2
|
+
|
|
3
|
+
Instructions for AI coding agents building an Angular app with `@spartan-native/helm`.
|
|
4
|
+
|
|
5
|
+
## What this package is
|
|
6
|
+
|
|
7
|
+
Layer 02 of Spartan Native (optional). `@spartan-native/theme` makes stock spartan/ui _look_ native. helm makes it _behave_ like a desktop app: OS-correct list and table selection, Enter/Esc on the default and cancel buttons, and dialog buttons in each OS's order. It's directives only. You keep using the stock `hlm*` components and add helm's attributes to them.
|
|
8
|
+
|
|
9
|
+
Requires `@spartan-native/theme` (with `provideSpartanNative()`) and its stylesheet.
|
|
10
|
+
|
|
11
|
+
```scss
|
|
12
|
+
// after the theme
|
|
13
|
+
@use '@spartan-native/theme/styles/spartan-native';
|
|
14
|
+
@use '@spartan-native/helm/styles/spartan-native-helm';
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Public API (`import … from '@spartan-native/helm'`)
|
|
18
|
+
|
|
19
|
+
| Import | Directives |
|
|
20
|
+
| --- | --- |
|
|
21
|
+
| `SnSelectableImports` | `snSelectable`, `snSelectableItem` |
|
|
22
|
+
| `SnDialogActionsImports` | `snDefaultAction`, `snCancelAction`, `snActionScope`, `snDialogButtons` |
|
|
23
|
+
| Pure functions | `selectionClick`, `selectionMoveTo`, `selectionMoveBy`, `selectionToggleActive`, `selectionAll`, `selectionClear`, `selectionSync`, `typeaheadIndex`, `EMPTY_SELECTION`, the constants `SELECTION_PAGE_SIZE` (10) and `TYPEAHEAD_RESET_MS` (600), types `SelectionState`, `SelectionModifiers` |
|
|
24
|
+
|
|
25
|
+
### Lists and tables: `snSelectable`
|
|
26
|
+
|
|
27
|
+
Use it for any list or table where users select rows (files, records, messages). Don't hand-roll click/Shift/Ctrl handling.
|
|
28
|
+
|
|
29
|
+
```html
|
|
30
|
+
<div snSelectable [(selection)]="selected" (activated)="open($event)" aria-label="Files">
|
|
31
|
+
@for (f of files(); track f.id) {
|
|
32
|
+
<div snSelectableItem [value]="f.id">{{ f.name }}</div>
|
|
33
|
+
}
|
|
34
|
+
</div>
|
|
35
|
+
|
|
36
|
+
<table hlmTable snSelectable="grid" [(selection)]="selected" aria-label="Backups">
|
|
37
|
+
<tbody hlmTBody>
|
|
38
|
+
@for (row of rows(); track row.id) {
|
|
39
|
+
<tr hlmTr snSelectableItem [value]="row.id">
|
|
40
|
+
…
|
|
41
|
+
</tr>
|
|
42
|
+
}
|
|
43
|
+
</tbody>
|
|
44
|
+
</table>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
- `selection`: two-way, the selected keys in row order. `multiple` defaults to `true`. `activated` emits a key on Enter or double-click.
|
|
48
|
+
- `snSelectableLabel` on a row sets its type-ahead text, when the visible text isn't the label.
|
|
49
|
+
- It handles: click, Ctrl-click (⌘ on macOS), Shift-click ranges, arrow keys, Home/End, PageUp/PageDown, Space, Ctrl/⌘+A, Esc, type-ahead. ARIA roles and `aria-selected` / `aria-activedescendant` are set for you, so don't add them yourself.
|
|
50
|
+
- Styling hooks: `[data-slot="sn-selectable-item"][data-selected]` and `[data-active]`. Colors come from the theme's `--sn-row-*` tokens. Derive secondary row text from `currentColor` so it stays readable on the macOS accent fill.
|
|
51
|
+
|
|
52
|
+
### Default and cancel buttons
|
|
53
|
+
|
|
54
|
+
```html
|
|
55
|
+
<form>
|
|
56
|
+
<input hlmInput />
|
|
57
|
+
<div snDialogButtons>
|
|
58
|
+
<button hlmBtn snDefaultAction (click)="save()">Save</button>
|
|
59
|
+
<button hlmBtn variant="outline" (click)="discard()">Don't save</button>
|
|
60
|
+
<button hlmBtn variant="outline" snCancelAction (click)="close()">Cancel</button>
|
|
61
|
+
</div>
|
|
62
|
+
</form>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
- `snDefaultAction` (only on a `<button>`): Enter anywhere in the surrounding `form`, `[role=dialog]`, `[role=alertdialog]` or `[snActionScope]` presses it. Enter is left alone in textareas, on other buttons and links, and in lists and menus. A disabled button is skipped.
|
|
66
|
+
- `snCancelAction` (only on a `<button>`): Esc in the same scope presses it.
|
|
67
|
+
- `snActionScope`: marks a custom area as a scope.
|
|
68
|
+
- **Every dialog and form with a primary action should mark its buttons with these.**
|
|
69
|
+
|
|
70
|
+
### Dialog button order: `snDialogButtons`
|
|
71
|
+
|
|
72
|
+
Write the buttons in any order. Mark the default and cancel buttons, and the skin places them:
|
|
73
|
+
|
|
74
|
+
| Skin | Order |
|
|
75
|
+
| ------------- | ---------------------------- |
|
|
76
|
+
| Windows, KDE | default · other · Cancel |
|
|
77
|
+
| macOS | other ‹gap› Cancel · default |
|
|
78
|
+
| GNOME | Cancel · other · default |
|
|
79
|
+
| ChromeOS, web | other · Cancel · default |
|
|
80
|
+
|
|
81
|
+
- `hlm-dialog-footer` and `hlm-alert-dialog-footer` get this automatically. Add `snDialogButtons` only to other button rows, such as a card footer (`<div hlmCardFooter snDialogButtons>`).
|
|
82
|
+
- A row with neither a default nor a cancel button keeps its source order.
|
|
83
|
+
- Don't re-sort buttons in code per OS, and don't use `flex-row-reverse` tricks.
|
|
84
|
+
- The per-skin tokens are `--sn-dialog-order-default|cancel|other` and `--sn-dialog-other-push`.
|
|
85
|
+
|
|
86
|
+
## Rules
|
|
87
|
+
|
|
88
|
+
1. Use the stock `@spartan-ng/helm/*` components and add helm directives to them. Don't wrap or fork them.
|
|
89
|
+
2. Selection keys must be stable (ids, not indexes): rows that disappear are dropped from the selection automatically.
|
|
90
|
+
3. The pure `selection*` functions work without Angular, for example in a store or a canvas list.
|
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,103 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @spartan-native/helm
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Layer 02 · optional.** Desktop **behaviors** for stock spartan/ui. `@spartan-native/theme` makes the components _look_ native; helm makes them _behave_ like a desktop app.
|
|
4
|
+
|
|
5
|
+
> Status: **first components implemented**: the desktop selection model and the default/cancel buttons. Spec: [`05-components.md`](https://github.com/Spartan-Native/spartan-native/blob/main/docs/05-components.md) (desktop interaction rules).
|
|
6
|
+
|
|
7
|
+
## Components
|
|
8
|
+
|
|
9
|
+
| Directive | What it does |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| `snSelectable` + `snSelectableItem` | The desktop selection model for lists (`snSelectable`, `role="listbox"`) and tables (`snSelectable="grid"`) |
|
|
12
|
+
| `snDefaultAction` | Enter in the surrounding dialog or form presses this button |
|
|
13
|
+
| `snCancelAction` | Esc in the surrounding dialog or form presses this button |
|
|
14
|
+
| `snActionScope` | Marks a custom area for the two above (dialogs and forms are scopes already) |
|
|
15
|
+
| `snDialogButtons` | A row of dialog buttons in the OS's order: default, cancel and other buttons move to where the skin puts them (`--sn-dialog-order-*`). hlm dialog and alert-dialog footers get this without the directive |
|
|
16
|
+
|
|
17
|
+
### Selection model
|
|
18
|
+
|
|
19
|
+
```html
|
|
20
|
+
<div snSelectable [(selection)]="selected" (activated)="open($event)" aria-label="Files">
|
|
21
|
+
@for (f of files; track f.id) {
|
|
22
|
+
<div snSelectableItem [value]="f.id">{{ f.name }}</div>
|
|
23
|
+
}
|
|
24
|
+
</div>
|
|
25
|
+
|
|
26
|
+
<table hlmTable snSelectable="grid" [(selection)]="selected">
|
|
27
|
+
<tbody hlmTBody>
|
|
28
|
+
@for (row of rows; track row.id) {
|
|
29
|
+
<tr hlmTr snSelectableItem [value]="row.id">
|
|
30
|
+
…
|
|
31
|
+
</tr>
|
|
32
|
+
}
|
|
33
|
+
</tbody>
|
|
34
|
+
</table>
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
| Input | Action |
|
|
38
|
+
| --- | --- |
|
|
39
|
+
| Click | Select one row |
|
|
40
|
+
| Ctrl-click (⌘-click on macOS) | Toggle a row |
|
|
41
|
+
| Shift-click | Select the range from the anchor (with Ctrl/⌘: add it) |
|
|
42
|
+
| ↑ ↓ · Home End · PageUp PageDown | Move and select; Shift extends; Ctrl moves the focus only; on macOS ⌘↑ / ⌘↓ jump to the ends |
|
|
43
|
+
| Space / Ctrl+Space | Select / toggle the focused row |
|
|
44
|
+
| Ctrl+A (⌘A) | Select all |
|
|
45
|
+
| Esc | Clear the selection (then lets a dialog close) |
|
|
46
|
+
| Typing | Jump to the next row starting with the typed text; a repeated letter cycles |
|
|
47
|
+
| Enter, double-click | `activated` emits the row's key |
|
|
48
|
+
|
|
49
|
+
Inputs: `selection` (two-way, keys in row order), `multiple` (default `true`), `snSelectableLabel` on a row for type-ahead text. ARIA: `listbox`/`option` or `grid`/`row`, `aria-selected`, `aria-multiselectable`, `aria-activedescendant`.
|
|
50
|
+
|
|
51
|
+
The logic is a set of pure functions in `selection-model.ts` (`selectionClick`, `selectionMoveBy`, `typeaheadIndex`, …), usable without Angular.
|
|
52
|
+
|
|
53
|
+
### Default and cancel buttons
|
|
54
|
+
|
|
55
|
+
```html
|
|
56
|
+
<form>
|
|
57
|
+
<input hlmInput />
|
|
58
|
+
<button hlmBtn variant="outline" snCancelAction (click)="close()">Cancel</button>
|
|
59
|
+
<button hlmBtn snDefaultAction (click)="save()">Save</button>
|
|
60
|
+
</form>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Enter is left alone in multi-line text, on other buttons and links, and in lists and menus. A disabled button is skipped.
|
|
64
|
+
|
|
65
|
+
## Styles
|
|
66
|
+
|
|
67
|
+
```scss
|
|
68
|
+
// after the theme
|
|
69
|
+
@use '@spartan-native/theme/styles/spartan-native';
|
|
70
|
+
@use '@spartan-native/helm/styles/spartan-native-helm';
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The styles contain **no per-OS rules**. They read the theme's row tokens, so each skin decides the look:
|
|
74
|
+
|
|
75
|
+
| Token | Windows 11 | macOS 26 | GNOME |
|
|
76
|
+
| --- | --- | --- | --- |
|
|
77
|
+
| `--sn-row-selected-bg` | neutral fill + accent pill (`--sn-row-selected-indicator`) | accent fill, white text | accent tint |
|
|
78
|
+
| `--sn-row-selected-bg-unfocused` | same | grey (also when the window is inactive) | same |
|
|
79
|
+
| `--sn-row-focus-ring` | 2px foreground | 2px accent | 2px accent |
|
|
80
|
+
|
|
81
|
+
Hooks: `[data-slot="sn-selectable"]`, `[data-slot="sn-selectable-item"]` with `[data-selected]` and `[data-active]`. Tip: derive secondary text in rows from `currentColor`, so it stays readable on the macOS accent fill.
|
|
82
|
+
|
|
83
|
+
## Structure
|
|
84
|
+
|
|
85
|
+
| Path | Purpose |
|
|
86
|
+
| -------------------- | ------------------------------------------------------------------ |
|
|
87
|
+
| `src/lib/selection/` | `selection-model.ts` (pure logic) and `selectable.ts` (directives) |
|
|
88
|
+
| `src/lib/actions/` | `snDefaultAction`, `snCancelAction`, `snActionScope` |
|
|
89
|
+
| `styles/` | Published as `@spartan-native/helm/styles/*` |
|
|
90
|
+
| `src/stories/` | Storybook: Selection (list, table), Default & cancel buttons |
|
|
91
|
+
| `.storybook/` | Toolbar from `@spartan-native/theme/storybook`, plus window focus |
|
|
92
|
+
|
|
93
|
+
## Dependencies
|
|
94
|
+
|
|
95
|
+
`@spartan-native/theme` (peer), Angular `^22.2.0`, spartan/ui `^1.9.0`. The stories use the stock spartan components from the workspace (`@spartan-ng/helm/*`).
|
|
96
|
+
|
|
97
|
+
## Commands
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
npm run storybook:helm # http://localhost:6007
|
|
101
|
+
npx ng test helm # 20 tests: selection model, directives, default/cancel
|
|
102
|
+
npx ng build helm
|
|
103
|
+
```
|