staffa 0.7.1 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staffa",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "An opinionated component library for the Aberdeen reactive UI library.",
   "license": "ISC",
   "author": "",
@@ -28,8 +28,7 @@
     "build": "npm run build:icons && tsc && tsc -p demo && esbuild src/index.ts --bundle --external:aberdeen --minify --format=esm --outfile=dist/staffa.esm.js",
     "build:skill": "rm -rf skill ; mkdir skill && readme-tsdoc --create src/index.ts --file skill/REFERENCE.md --split && awk '/^@@include /{while((getline line < $2)>0) print line; close($2); next} 1' skill-template.md > skill/SKILL.md && rm skill/REFERENCE.md",
     "typecheck": "tsc --noEmit && tsc -p demo --noEmit",
-    "smoke": "tsc && node smoke.mjs",
-    "prepublish": "npm run build && shotest test && npm run build:skill",
+    "prepublishOnly": "npm run build && npx shotest test --fail-on-visual-changes && npm run build:skill",
     "test": "shotest test"
   },
   "peerDependencies": {

package/skill/ButtonOptions.md

@@ -48,7 +48,7 @@ Accessible label, when the button has only an icon.
 
 Aberdeen attr/style string applied to the button. A button is a surface, so
 pass surface modifier classes here to restyle it, e.g. `".danger"`,
-`".danger .outlined"`, or `".nest"` for a neutral button. Defaults to a
+`".danger .outlined"`, or `".neutral"` for a neutral button. Defaults to a
 filled `.primary` surface.
 
 Size is set here too, with `.small` or `.large` (medium is the default and

package/skill/FloatingMenuOptions.md

@@ -14,6 +14,22 @@ Element to anchor the menu to (positioned just below it, flips up if needed).
 
 **Type:** `HTMLElement`
 
+### floatingMenuOptions.at · member
+
+Position the menu at this viewport point (e.g. a pointer location) instead
+of just below the anchor. Used by `addContextMenu` to open at the
+exact click/tap target.
+
+**Type:** `{ x: number; y: number; }`
+
+### floatingMenuOptions.closeOnAnchorClick · member
+
+Also close the menu when the anchor itself is clicked. By default a click on
+the anchor is ignored (so a trigger button can run its own toggle), but a
+context menu — whose anchor has no click handler — wants the click to close.
+
+**Type:** `boolean`
+
 ### floatingMenuOptions.dropdownAttrs · member
 
 Aberdeen attr/style string on the floating panel.

package/skill/SKILL.md

@@ -82,22 +82,22 @@ S.box({ header: "See the [docs](/docs)", content: () => { ... } });
 
 Staffa builds on **surfaces**: elements marked with `.s-s` that have their own background and derived text/border tokens. There are two families:
 
-- **Nesting surfaces** — `.nest` (and the implicit page at `:root`). A calm neutral whose shade steps automatically with nesting depth (page → panel → raised, capped). Use them for cards, bars, popovers — anything that just holds content. No variants.
-- **Solid surfaces** — `.primary`, `.danger`, `.success`, `.warning`, `.link` (a bare `.s-s` defaults to primary). A bright fill with white ink, painted as a subtle single-colour gradient. They take a **variant**: `.filled` (default), `.tonal`, or `.outlined`. A surface nested *inside* a solid surface is always rendered filled, so it can't bleed into the vivid parent.
+- **Neutral surfaces** — `.neutral` (and the implicit page at `:root`). A calm neutral whose shade steps automatically with nesting depth (page → panel → raised, capped). Use them for cards, bars, popovers — anything that just holds content. No variants.
+- **Accent surfaces** — `.primary`, `.danger`, `.success`, `.warning`, `.link` (a bare `.s-s` defaults to primary). A bright fill with white ink, painted as a subtle single-colour gradient. They take a **variant**: `.filled` (default), `.tonal`, or `.outlined`. A surface nested *inside* an accent surface is always rendered filled, so it can't bleed into the vivid parent.
 
-Components are built from these (`S.button` is a `.s-s.primary`, `S.box` a `.s-s.nest`, etc.). Because component options include an optional `attrs` string, which has Aberdeen `A()` string semantics, you can easily override it:
+Components are built from these (`S.button` is a `.s-s.primary`, `S.box` a `.s-s.neutral`, etc.). Because component options include an optional `attrs` string, which has Aberdeen `A()` string semantics, you can easily override it:
 
 ```ts
 S.button({ content: "Delete", attrs: ".danger" });
-S.button({ content: "Cancel", attrs: ".nest" });          // neutral button
+S.button({ content: "Cancel", attrs: ".neutral" });       // neutral button
 S.box({ attrs: ".primary", content: () => { ... } });
 ```
 
-Inside any surface (including `:root`), CSS variables are defined for the background and a set of safe foreground colors: `$s-bg`, `$s-text` (also applied as `color`), `$s-muted`, `$s-accent` (the surface's "pop" — the brand primary on nesting surfaces, the ink on solid surfaces), and `$s-faint`. By using these, components adapt to wherever they're nested.
+Inside any surface (including `:root`), CSS variables are defined for the background and a set of safe foreground colors: `$s-bg`, `$s-text` (also applied as `color`), `$s-muted`, `$s-accent` (the surface's "pop" — the brand primary on neutral surfaces, the ink on accent surfaces), and `$s-faint`. By using these, components adapt to wherever they're nested.
 
-The colour tokens are mode-independent and settable: `$s-primary` (the one brand colour — it tints the neutrals and defines `.s-s.primary`), `$s-danger`, `$s-success`, `$s-warning`, and `$s-link` (the link colour, which is also the fill of the `.s-s.link` surface). Links render in `$s-link` on nesting surfaces and in the ink on solid surfaces.
+The colour tokens are mode-independent and settable: `$s-primary` (the one brand colour — it tints the neutrals and defines `.s-s.primary`), `$s-danger`, `$s-success`, `$s-warning`, and `$s-link` (the link colour, which is also the fill of the `.s-s.link` surface). Links render in `$s-link` on neutral surfaces and in the ink on accent surfaces.
 
-**Borders & shadows.** Nesting surfaces carry a subtle hairline border on their own (so a card looks like a card without any component help). Any surface can be lifted with `.shadow` or `.extra-shadow`: on a nesting surface that's a neutral drop shadow, on a solid surface it's a self-coloured glow (a lit button is just a `.primary` surface with `.shadow`), and on `.tonal`/`.outlined` it's ignored. `.no-shadow` removes a component's built-in shadow:
+**Borders & shadows.** Neutral surfaces carry a subtle hairline border on their own (so a card looks like a card without any component help). Any surface can be lifted with `.shadow` or `.extra-shadow`: on a neutral surface that's a neutral drop shadow, on an accent surface it's a self-coloured glow (a lit button is just a `.primary` surface with `.shadow`), and on `.tonal`/`.outlined` it's ignored. `.no-shadow` removes a component's built-in shadow:
 
 ```ts
 S.box({ attrs: ".extra-shadow", content: () => { ... } });   // a more raised card
@@ -132,7 +132,7 @@ A.cssVars["s-radius"] = "4px";
 
 See `src/theme.ts` for what other CSS variables are being used.
 
-If you need further customization, just add some CSS to override the default styling. For instance, to add your own solid surface, set its background (and, if needed, its ink) — the subtle gradient and the rest of the tokens follow automatically:
+If you need further customization, just add some CSS to override the default styling. For instance, to add your own accent surface, set its background (and, if needed, its ink) — the subtle gradient and the rest of the tokens follow automatically:
 
 ```ts
 A.insertGlobalCss({".s-s.my-surface": "--s-bg:#ef6b00 --s-text:#fff"});
@@ -250,7 +250,7 @@ Staffa is designed for extension. A component is simply a plain function taking
 
 3. **Reach for reactivity deliberately.** Pass option strings straight to `A` as positional args (the caller's scope). Only wrap a dedicated `A(() => ...)` scope where it matters: input elements (recreation loses focus), or large subtrees you don't want to redraw. Use `A.peek(() => ...)` when you need a value but must not subscribe.
 
-4. **Build on surfaces.** Mark elements `.s-s` and add `.nest` (neutral) or a solid role (`.primary`, `.danger`, …) plus an optional variant. Inside them, use the contextual CSS variables (`$s-text`, `$s-bg`, `$s-muted`, `$s-accent`, `$s-faint`, ...) so components adapt to wherever they're nested. Hard-coding colors in components shouldn't be needed, but if you must, make sure you set *both* foreground and background.
+4. **Build on surfaces.** Mark elements `.s-s` and add `.neutral` or an accent role (`.primary`, `.danger`, …) plus an optional variant. Inside them, use the contextual CSS variables (`$s-text`, `$s-bg`, `$s-muted`, `$s-accent`, `$s-faint`, ...) so components adapt to wherever they're nested. Hard-coding colors in components shouldn't be needed, but if you must, make sure you set *both* foreground and background.
 
 5. **No outer margins.** Components don't margin themselves; spacing is the parent's job. Content components set default `padding` on the content element; `contentAttrs` overrides it.
 
@@ -302,13 +302,11 @@ ln -s ../../node_modules/staffa/skill .claude/skills/staffa
 
 ## Breaking changes
 
-- **0.7** — the surface model was simplified to two families: **nesting** (`.nest`) and **solid** (`.primary`/`.danger`/`.success`/`.warning`/`.link`).
-  - Surface levels `.base`/`.panel`/`.raised`/`.neutral` are replaced by a single `.nest` class whose shade steps with nesting depth. Replace them all with `.nest` (a neutral *button* is `.nest` too, in place of `.neutral .outlined`).
-  - `.secondary` and `.gradient` are gone: there is no more `s-secondary` colour, and the default button is `.primary` (which now carries a subtle auto-gradient). Drop `s-secondary` overrides.
-  - Solid surfaces now use **white** ink (was near-black), and the brand/semantic colours (`s-primary`/`s-danger`/`s-success`/`s-warning`) are now a single mode-independent value each.
-  - New: a `s-link` colour and a matching `.s-s.link` surface. Links use `s-link` on nesting surfaces, the ink on solid ones.
-  - Nesting surfaces now carry their own hairline border, and `.shadow`/`.extra-shadow`/`.no-shadow` utilities work on any surface. `S.box` no longer draws its own border/shadow (they come from the surface); pass `.no-shadow` to `S.box`/`S.button` to drop the default elevation.
-  - Contextual tokens were renamed/trimmed: `--s-fg`→`--s-text`, `--s-fg-muted`→`--s-muted`, `--s-border`→`--s-faint`; `--s-strong`, `--s-fg-faint`, `--s-border-strong`, `--s-on-accent`, `--s-ink`, `--s-page`/`--s-panel`/`--s-raised`, `--s-tint`, `--s-glow`, `--s-shadow`, `--s-gradient-surface`, and the `--s-a`/`--s-b` anchors were removed. Custom solid surfaces now set `--s-bg`/`--s-text`.
+- **0.7** — the surface model was reduced to two families: **neutral** (`.neutral`) and **accent** (`.primary`/`.danger`/`.success`/`.warning`/`.link`). Apps that only use the high-level `S.*` components need no changes. Code that uses surface classes or tokens directly must update:
+  - **Surface levels gone.** Replace `.base`/`.panel`/`.raised`/`.neutral`/`.nest` with the single `.neutral` class.
+  - **`.secondary` and `.gradient` gone.** Drop any `s-secondary` colour override; there's no `s-secondary` anymore. The default button is now `.primary`.
+  - **Tokens renamed.** `--s-fg`→`--s-text`, `--s-fg-muted`→`--s-muted`, `--s-border`→`--s-faint`. Removed: `--s-fg-faint`, `--s-border-strong`, `--s-ink`, `--s-on-accent`, `--s-page`/`--s-panel`/`--s-raised`, `--s-neutral`, `--s-tint`, `--s-glow`, `--s-shadow`, `--s-gradient-surface`. A custom surface now sets `--s-bg`/`--s-text` (was the `--s-a`/`--s-b` anchors).
+  - **Borders/shadows moved onto surfaces.** Components no longer draw their own border/shadow. If you relied on `S.box`/`S.dialog`/etc. elevation, it now comes from the surface; pass `.no-shadow` to drop it, or `.shadow`/`.extra-shadow` to add it on any surface.
 
 - **0.6**: None.
 
@@ -480,7 +478,7 @@ Options for `showFloatingMenu`.
 Options for `addContextMenu` — like `FloatingMenuOptions`, but
 the anchor is the element the handler is attached to.
 
-**Type:** `Omit<FloatingMenuOptions, "anchor">`
+**Type:** `Omit<FloatingMenuOptions, "anchor" | "at" | "closeOnAnchorClick">`
 
 ## [dialog](dialog.md) · function
 

package/skill/button.md

@@ -24,7 +24,7 @@ S.button({ href: "/dashboard", content: "Dashboard" }); // navigates via router
 
 ```ts
 S.button({ content: "Save", click: S.alert("Saved.") });
-S.button({ content: "Cancel", attrs: ".nest", click: cancel }); // neutral button
+S.button({ content: "Cancel", attrs: ".neutral", click: cancel }); // neutral button
 S.button({ content: "Delete", attrs: ".danger .outlined", click: del });
 S.button("Cancel");                        // shorthand for { content: "Cancel" }
 S.button({ href: "/docs", content: "Docs" }); // renders an <a role=button>

package/skill/buttonGroup.md

@@ -15,8 +15,8 @@ If you want a single button to be *selected*, use `buttonChooser`.
 
 ```ts
 S.buttonGroup({ buttons: [
-  { content: "Day", attrs: ".nest" },
-  { content: "Week", attrs: ".nest" },
-  { content: "Month", attrs: ".nest" },
+  { content: "Day", attrs: ".neutral" },
+  { content: "Week", attrs: ".neutral" },
+  { content: "Month", attrs: ".neutral" },
 ]});
 ```

package/skill/dialog.md

@@ -22,7 +22,7 @@ S.dialog({
   content: (close) => {
     A("p #Are you sure?");
     S.button({ content: "Yes", click: () => { S.alert("Nice!"); close(); } });
-    S.button({ content: "Cancel", attrs: ".nest", click: close });
+    S.button({ content: "Cancel", attrs: ".neutral", click: close });
   },
 });
 ```

package/skill/menuButton.md

@@ -17,7 +17,7 @@ for SPA navigation — active items are highlighted automatically.
 
 ```ts
 S.menuButton({
-  button: { content: "Actions", attrs: ".nest" },
+  button: { content: "Actions", attrs: ".neutral" },
   items: [
     { label: "Edit", icon: () => A("#✎"), click: () => edit() },
     { separator: true },