@nxgt/material 3.60.0 → 3.63.0

package/docs/guides/illustrations.md

@@ -5,7 +5,7 @@ on a Material 3 Expressive plate, two to four satellite icons around it, a
 dashed ring and a few sparkles. There are twelve scenes: `empty`, `no-results`,
 `not-found`, `error`, `offline`, `success`, `welcome`, `forbidden`,
 `maintenance`, `invitation`, `sign-in` and `empty-inbox`, and two domain sets of
-ten more each, health and education, in their own entries ([health](#scene-sets-the-health-scenes) and [education](#scene-sets-the-education-scenes)). The icons are
+ten more each, health and education, in their own entries ([health](#scene-sets-the-health-scenes) and [education](#scene-sets-the-education-scenes)), and eleven for games ([game](#scene-sets-the-game-scenes)). The icons are
 [Font Awesome](https://fontawesome.com) sprites **your app serves** (see
 [Icons](../getting-started.md#icons)): the package ships no icon artwork, so it
 works with the sprites your licence covers. The [icon motifs guide](icon-motifs.md) shows them next to the icon backgrounds, the sky and the themes, and lists the suggested names that are Pro only, with Free neighbours.
@@ -146,6 +146,38 @@ the icon names the set draws, hero first. Some of them (`backpack`,
 `clipboard-list-check`, `books`, `file-chart-column`) are Font Awesome Pro
 icons: serve a Pro sprite, or set `edition="free"` on `IconSpritesProvider`, which draws their Free twins (see the [Free edition](icon-motifs.md#the-free-edition)).
 
+## Scene sets: the game scenes
+
+`@nxgt/material/illustrations/game` holds eleven scenes for a game, a quiz, a
+community or an event app: `night-sky`, `village`, five character pictograms
+(`seer`, `healer`, `archer`, `cupid`, `wolf`), `victory`, `empty-table`,
+`waiting-players` and `connection-lost`. It works exactly like the other sets,
+and they register side by side. Use them where a screen is empty, waiting,
+failed, celebrating or opening: a lobby with no players, a round that waits, a
+dropped connection, a winner, a night-phase hero. Keep them away from behind
+data.
+
+<img src="../previews/feedback-status-illustration-game.webp" width="480" alt="The eleven game scenes">
+
+```tsx
+import { Illustration, IllustrationDefaults } from '@nxgt/material/illustrations';
+import { GAME_SCENES } from '@nxgt/material/illustrations/game';
+import { EmptyState } from '@nxgt/material/components';
+
+<IllustrationDefaults sets={[GAME_SCENES]}>
+  <Illustration scene="night-sky" />                {/* decorative: aria-hidden */}
+  <Illustration scene="victory" title="Victory" />  {/* role="img" + aria-label */}
+  <EmptyState illustration="empty-table" title="No one at the table" />
+</IllustrationDefaults>
+```
+
+Colours come from the theme's tone tokens (light and dark follow the theme),
+motion stops under `prefers-reduced-motion`, and a scene is 120, 190 or 280 px
+wide (`size`), never wider than its container. The `night-sky` scene is
+unrelated to the `night-sky` Background preset. Every icon is in the Free sheet, so `edition="free"`
+needs no substitution; `GAME_SUGGESTED_ICONS` lists the names, hero first.
+Importing the entry adds the ids to `SceneId`.
+
 ## Turn them on for an app
 
 `IllustrationDefaults` opts a subtree in: every default-size `EmptyState` and

package/docs/guides/migrating-to-3.md

@@ -59,7 +59,8 @@ component`). As a peer there is one copy, your app's.
 ## ActivityLayout animates route changes (`routeTransition`)
 
 3.0 wraps the content region of `ActivityLayout` in React's `<ViewTransition>`,
-on by default: a navigation cross-fades the page, the sidebar, header and
+on by default: a navigation cross-fades the page (only when the pathname
+changes; see [Route transitions](./app-shell.md#route-transitions)), the sidebar, header and
 breadcrumb staying still. Back and Forward may not animate (React skips view
 transitions for synchronous popstate updates).
 
@@ -92,7 +93,8 @@ shell's off with `routeTransition={false}`, or remove yours:
 ```
 
 The prop is `routeTransition?: boolean | Omit<ViewTransitionProps, 'children' | 'ref'>`,
-default `true`. An object turns it on and passes its props through, so the app
+default `true` (it fades only when the pathname changes; see
+[Route transitions](./app-shell.md#route-transitions)). An object turns it on and passes its props through, so the app
 can pick its own classes: `routeTransition={{ default: 'my-route' }}`.
 
 **Nested boundaries.** An inner `<ViewTransition>` takes the mutation from the

package/docs/guides/theming.md

@@ -620,15 +620,16 @@ descendant of it: an element that reads `--nxgt-tone-container` needs its own
 ## The active entry of the sidebar and the rail
 
 The selected `SidebarMenuItem` (and so the `AppSidebar` and `ActivityLayout`
-rail and menu sheet) is drawn with three tokens, in light and in dark:
+rail and menu sheet) is drawn with four tokens, in light and in dark:
 
 | Token | Tailwind | Default, light | Default, dark |
 | --- | --- | --- | --- |
 | `--sidebar-active` | `bg-sidebar-active` | primary at 15 % | primary at 30 % |
 | `--sidebar-active-hover` | `bg-sidebar-active-hover` | primary at 20 % | primary at 35 % |
 | `--sidebar-active-foreground` | `text-sidebar-active-foreground` | `oklch(from var(--primary) calc(l * 0.85) c h)`, 4.5:1 or more on the pill for every theme preset | `oklch(from var(--primary) 0.72 0.15 h)`, 6.3:1 or more on the pill |
+| `--sidebar-active-edge` | `bg-sidebar-active-edge` | the value of `--sidebar-active-foreground` | the value of `--sidebar-active-foreground` |
 
-The pill is the icon's (collapsed rail) or the whole row (expanded), a pill in the collapsed rail and, in the expanded row, an `--nxgt-item-radius` (6px) shape that carries the 3px start bar every chosen row has, drawn in `--sidebar-active-foreground` (a `Highlight` bar in forced colours); the
+The pill is the icon's (collapsed rail) or the whole row (expanded), a pill in the collapsed rail and, in the expanded row, an `--nxgt-item-radius` (6px) shape that carries the 3px start bar every chosen row has, drawn in `--sidebar-active-edge` (a `Highlight` bar in forced colours); the
 foreground is the label and the icon, whose duotone layers both follow it (in
 dark too: the icon of `AppSidebar` is the lifted lavender like its label). The
 label is read on the pill (expanded) or on the sidebar (collapsed rail); the
@@ -639,9 +640,18 @@ itself in light and dark, as both the light darkening and the dark lift need
 
 The defaults are derived where the entry is drawn, from the `--primary` it
 sits under, so a `--primary` set on a wrapper recolours the rail inside it.
-The three tokens are not declared on `:root`: setting one replaces its
+The four tokens are not declared on `:root`: setting one replaces its
 default wherever it is set.
 
+`--sidebar-active-edge` recolours the start bar alone; unset, the bar follows
+the foreground:
+
+```css
+:root {
+  --sidebar-active-edge: oklch(0.8 0.15 90);
+}
+```
+
 Set them after importing the stylesheet, under the same selectors as the
 theme, for example a rail in the `maths` colour:
 

package/docs/roadmap.md

@@ -250,7 +250,7 @@ version they shipped in, and planned entries may name the major they target.
   (`name` for a key, `range` for a value), as it does for the icon keys.
 
 - **More illustration sets** — finance, travel and tech scenes beside the
-  health and education sets, each in its own subpath.
+  health, education and game sets, each in its own subpath.
 - **More generic scenes** — further base scenes for `Illustration` beyond the
   twelve it draws today (`forbidden`, `maintenance`, `invitation`, `sign-in`
   and `empty-inbox` are among them), added on demand.

package/docs/troubleshooting.md

@@ -2724,10 +2724,12 @@ See [Route transitions](./guides/app-shell.md#route-transitions).
 **When:** after upgrading to `@nxgt/material` 3.0, a filter, a tab switch, a
 `useDeferredValue` update or a lazy part loading inside `ActivityLayout`'s
 content fades the whole page, as a navigation does.
-**Why:** the shell's `<ViewTransition>` animates every transition that changes
-its content region, not only navigations: your `startTransition`,
-`useDeferredValue` and Suspense reveals too. The Gallery's morph is the one
-exception the shell makes itself.
+**Why:** the default fades the region only when the pathname changes, so a
+filter or a `?tab=` change does not fade it. Two cases still do: an explicit
+`routeTransition={{ default: 'nxgt-route' }}`, which animates every transition
+that changes the region (your `startTransition`, `useDeferredValue`, Suspense
+reveals), and a Suspense reveal or a transition that changes the pathname on the
+default. The Gallery's morph is the one exception the shell makes itself.
 **Fix:** give your transition a type and map that type to `'none'`:
 
 ```tsx
@@ -7801,14 +7803,15 @@ z.config({ jitless: true });
 ### `Illustration: … Drawing the built-in art instead.`
 
 **When:** a development-only `console.warn`, once per message, from an `Illustration` (or an `EmptyState` / `ErrorState` with `illustration`) that cannot be built. The page does not break: the built-in art of the scene's kind is drawn, and production builds do it silently.
-**Why:** the scene id is in no table (`"patient-record" is not a scene of the table`), an icon name is not valid, or the style is not one Font Awesome 7.3.1 draws. A domain id such as `patient-record` (health) or `classroom` (education) is only a scene when its set is registered; in an `EmptyState`, `illustration="no-patients"` or `"no-students"` is otherwise drawn as text.
+**Why:** the scene id is in no table (`"patient-record" is not a scene of the table`), an icon name is not valid, or the style is not one Font Awesome 7.3.1 draws. A domain id such as `patient-record` (health) `classroom` (education) or `village` (game) is only a scene when its set is registered; in an `EmptyState`, `illustration="no-patients"`, `"no-students"` or `"empty-table"` is otherwise drawn as text.
 **Fix:** register the set once for the subtree, or pass it to the one `Illustration`; and take `iconStyle` from the 37 sprite file names (a bad name is a type error):
 
 ```tsx
 import { EDUCATION_SCENES } from '@nxgt/material/illustrations/education';
+import { GAME_SCENES } from '@nxgt/material/illustrations/game';
 import { HEALTH_SCENES } from '@nxgt/material/illustrations/health';
 
-<IllustrationDefaults sets={[HEALTH_SCENES, EDUCATION_SCENES]}>
+<IllustrationDefaults sets={[HEALTH_SCENES, EDUCATION_SCENES, GAME_SCENES]}>
   <EmptyState illustration="no-patients" />
 </IllustrationDefaults>;
 

package/lib/components/ui/layout/sidebar/sidebar-tokens.css

@@ -8,7 +8,9 @@
 	 * follow a `--primary` set below :root. To theme the rail set
 	 * `--sidebar-active`, `--sidebar-active-hover` and
 	 * `--sidebar-active-foreground` (all three, or the first two and the
-	 * foreground); the derived colours are not declared here, on purpose. */
+	 * foreground); the derived colours are not declared here, on purpose.
+	 * `--sidebar-active-edge` recolours the start bar alone; unset, the bar is
+	 * the foreground (`--sidebar-active-edge: gold` changes nothing else). */
 	--nxgt-sidebar-active-share: 15%;
 	/* Light: primary itself reads 4.5:1 on the page but not on its own 15 % pill
 	 * for every preset (corail 3.7:1), so the label is primary darkened to 85 %
@@ -71,4 +73,14 @@
 				var(--nxgt-sidebar-active-c, c) h
 		)
 	);
+	--color-sidebar-active-edge: var(
+		--sidebar-active-edge,
+		var(
+			--sidebar-active-foreground,
+			oklch(
+				from var(--primary) var(--nxgt-sidebar-active-l, l)
+					var(--nxgt-sidebar-active-c, c) h
+			)
+		)
+	);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.60.0",
+	"version": "3.63.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -105,6 +105,11 @@
 			"types": "./dist/lib/illustrations-education/index.d.ts",
 			"require": "./dist/illustrations-education.js"
 		},
+		"./illustrations/game": {
+			"import": "./dist/illustrations-game.js",
+			"types": "./dist/lib/illustrations-game/index.d.ts",
+			"require": "./dist/illustrations-game.js"
+		},
 		"./themes": {
 			"import": "./dist/themes.js",
 			"types": "./dist/lib/themes/index.d.ts",
@@ -367,7 +372,7 @@
 		"docs:previews": "rm -rf node_modules/.cache/nxgt-preview-free/missing && NXGT_PREVIEW_FREE=1 vitest run --project previews && bun .storybook/preview-free-report.ts"
 	},
 	"dependencies": {
-		"@nxgt/material-core": "^0.43.0",
+		"@nxgt/material-core": "^0.44.0",
 		"@base-ui/react": "^1.6.0",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",