@maggioli-design-system/magma-react 2.2.0 → 2.4.0

package/agents/anti-patterns.md

@@ -19,10 +19,13 @@
   properties and, for a deep customisation, the parts listed in the component's
   `AGENTS.md` (see [`conventions.md`](conventions.md)).
 - Setting boolean attributes to the string `"false"` (e.g. `disabled="false"`,
-  `await="false"`). Stencil reads `"false"` as `false`, but the attribute stays in the
-  DOM on a prop that is not reflected (and until the first render on one that is), so
-  `[disabled]` selectors and scripts reading the attribute still see it set. **Remove
-  the attribute** to turn it off.
+  `await="false"`). On a form-associated component (`mds-button`, `mds-button-dropdown`
+  and the form inputs, listed in [`conventions.md`](conventions.md)) it turns the prop
+  **on**, as on a native control. On the others Stencil reads `"false"` as `false`, but
+  the attribute stays in the DOM on a prop that is not reflected (and until the first
+  render on one that is), so `[disabled]` selectors and scripts reading the attribute
+  still see it set. **Remove the attribute** to turn it off; from React or Angular, pass
+  `false` to the property, as [`conventions.md`](conventions.md) shows.
 - Embedding nested HTML in a default slot when the component documents a `label` prop.
 - Using raw Tailwind colour utilities (`bg-white`, `text-gray-700`) on or inside Magma
   components - use the semantic role classes (`bg-surface-default`, `text-fg-muted`),

package/agents/assets.md

@@ -8,8 +8,8 @@
 ## Purpose
 
 Canonical setup for the assets every Magma consumer needs, **identical for all three
-targets** (web components, React, Angular): styles, fonts, icons and optional brand
-identity. The per-target tracks ([`install.md`](install.md)) link here instead of repeating
+targets** (web components, React, Angular): styles, fonts, icons, optional brand
+identity and editor autocomplete. The per-target tracks ([`install.md`](install.md)) link here instead of repeating
 this. If something about styles/fonts/icons setup is unclear, this file wins.
 
 This file is the minimum to get a consumer running. Once it runs: coloring your own UI
@@ -72,10 +72,10 @@ What each file provides:
 | `colors-rgb.css` | RGB color tokens (`--tone-*`, `--status-*`, ...). Required by components and Tailwind. Also redefines tokens for dark / high-contrast |
 | `typography.css` | The non-color tokens as CSS vars: fonts, type sizes, spacing, radius, shadows (`--shadow-md-sharp`, ...). Components carry their own fallbacks; your CSS needs this file for `var(--shadow-*)`, `var(--radius-*)` and the `--magma-radius-*` corner scale |
 | `reset.css` | Opinionated CSS reset |
-| `hydrated.css` | Anti-FOUC for Stencil - hides components until hydrated |
+| `hydrated.css` | Anti-FOUC for Stencil - hides components until hydrated, then keeps the margin, padding and border they give themselves against a page reset such as Tailwind's preflight. Import it into `base`, as above |
 | `transitions.css`, `animations.css` | Shared motion |
 | `globals.css` | Global `--magma-*` design decisions |
-| `semantic.css` | The semantic color roles (`--magma-surface-*`, `--magma-text-*`, ..., see [`color.md`](color.md)). Required: without it the page `body` has no colour, the Tailwind role utilities paint nothing, and components lose named themes and high contrast |
+| `semantic.css` | The semantic color roles (`--magma-surface-*`, `--magma-text-*`, ..., see [`color.md`](color.md)). Required: without it the page `body` has no colour, the Tailwind role utilities are stuck on their light default (the fallback that gives editors a swatch), and components lose dark mode, named themes and high contrast |
 | `themes.css` | The named themes (`data-theme-name`): retint the semantic roles. Import it after `semantic.css` |
 | `base.css` | Base element styles (sets `--font-info` body font, etc.) |
 
@@ -129,40 +129,173 @@ the `vendor` cascade layer and ship offline.
 ## 3. Icons
 
 Icons are consumed at runtime by `mds-icon`, which fetches each icon as an SVG file from
-a path the host app configures. A slug starts with its icon set (`mi/` Material Icons,
-`mdi/` Material Design Icons, `mgg/` Maggioli) and resolves to
-`<mdsIconSvgPath><slug>.svg`: with the path `/svg/`, `mi/baseline/email` is fetched from
-`/svg/mi/baseline/email.svg`.
+a path the host app configures. The components' own icons are inlined, so what needs
+serving is the icons the app names.
 
-### Package and asset copy
+### The contract
+
+Every slug the app uses must be served at `<mdsIconSvgPath><slug>.svg`: with the path
+`/svg/`, `mi/baseline/email` is fetched from `/svg/mi/baseline/email.svg`. A slug starts
+with its icon set, and each set comes from its own package, with its own layout:
+
+| Slug | Set | Package | File in the package |
+| ---- | --- | ------- | ------------------- |
+| `mi/<variant>/<name>` | Material Icons | `@material-icons/svg` | `svg/<name>/<variant>.svg` |
+| `mdi/<name>` | Material Design Icons | `@mdi/svg` | `svg/<name>.svg` |
+| `mgg/<name>` | Maggioli | `@maggioli-design-system/svg-icons` | `dist/svg/<name>.svg` |
+
+Magma ships only the `mgg/` set, and none of these packages is a dependency of `magma`,
+`magma-react` or `magma-angular`: the route you pick installs what it needs. Copying the
+`svg-icons` folder as it is does NOT follow the contract: its files sit directly in
+`dist/svg/`, while `mds-icon` asks for them under `mgg/`.
+
+`mds-usage` still fetches `mi/baseline/info` for its header: serve it too if the app
+uses that component.
+
+Any setup that follows the contract works. Two tested routes, both run before every dev
+start and build, with the output folder kept out of git:
+
+### Route 1: iconsauce (what Magma uses)
+
+iconsauce reads the sources the way Tailwind reads class names and writes only the icons
+they use, one SVG file per slug, in the folders `mds-icon` expects. Its plugins know the
+three sets and bring their packages along.
 
 ```bash
-npm i @maggioli-design-system/svg-icons
+npm i -D @iconsauce/core @iconsauce/material-icons @iconsauce/mdi-svg @iconsauce/mgg-icons
 ```
 
-Copy the SVG library to a publicly served path. The package ships the files under
-`@maggioli-design-system/svg-icons/dist/svg/`. Copy them to e.g. `public/svg/` (the
-mechanism depends on the bundler - see each track file).
+```js
+// iconsauce.config.mjs
+import mi from '@iconsauce/material-icons';
+import mdi from '@iconsauce/mdi-svg';
+import mgg from '@iconsauce/mgg-icons';
 
-### Tell mds-icon where the icons are
+export default {
+  content: ['./index.html', './src/**/*.{html,js,jsx,ts,tsx}'], // every file where icon slugs are written
+  plugin: [mi, mdi, mgg],
+};
+```
 
-The simplest way: set `mdsIconSvgPath` in `sessionStorage` before components hydrate.
-The value is the public URL of the folder you copied the SVGs into:
+```json
+"scripts": {
+  "icons": "iconsauce --config ./iconsauce.config.mjs --output-svg ./public/svg",
+  "predev": "npm run icons",
+  "prebuild": "npm run icons"
+}
+```
 
-```javascript
-window.sessionStorage.setItem('mdsIconSvgPath', '/svg/');
+A slug built at runtime (`'mi/baseline/' + name`) is invisible to iconsauce: write slugs
+in full, or list the computed ones in a file that `content` reads.
+
+### Route 2: serve the files yourself
+
+One renaming step: `@material-icons/svg` stores `<name>/<variant>.svg`, while the slug
+wants `mi/<variant>/<name>`. `mdi/` and `mgg/` are plain folder copies. This script covers
+the three sets with Node built-ins only, so it fits any bundler:
+
+```bash
+npm i -D @maggioli-design-system/svg-icons @material-icons/svg @mdi/svg
 ```
 
-Alternatives, documented in
-the mds-icon readme:
+```js
+// scripts/copy-icons.mjs
+// Copies Magma's icon sets where mds-icon fetches them: <OUT>/<slug>.svg.
+//   node scripts/copy-icons.mjs icons.json   only the slugs listed in icons.json
+//   node scripts/copy-icons.mjs              every icon of the three sets (18,720 files, 73 MB)
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const OUT = 'public/svg'; // served at /svg/ by Vite, Next.js and the Angular CLI
+const require = createRequire(import.meta.url);
+const root = (pkg) => dirname(require.resolve(`${pkg}/package.json`));
+const MI = join(root('@material-icons/svg'), 'svg'); // <name>/<variant>.svg
+const MDI = join(root('@mdi/svg'), 'svg'); // <name>.svg
+const MGG = join(root('@maggioli-design-system/svg-icons'), 'dist/svg'); // <name>.svg
+
+// Source file of a slug: mi/<variant>/<name>, mdi/<name>, mgg/<name>.
+function source(slug) {
+  const [set, ...rest] = slug.split('/');
+  if (set === 'mi' && rest.length === 2) return join(MI, rest[1], `${rest[0]}.svg`);
+  if (set === 'mdi' && rest.length === 1) return join(MDI, `${rest[0]}.svg`);
+  if (set === 'mgg' && rest.length === 1) return join(MGG, `${rest[0]}.svg`);
+  throw new Error(`Not a Magma icon slug: ${slug}`);
+}
+
+function allSlugs() {
+  const names = (dir) => readdirSync(dir).map((file) => file.replace(/\.svg$/, ''));
+  return [
+    ...readdirSync(MI).flatMap((name) => names(join(MI, name)).map((variant) => `mi/${variant}/${name}`)),
+    ...names(MDI).map((name) => `mdi/${name}`),
+    ...names(MGG).map((name) => `mgg/${name}`),
+  ];
+}
+
+const slugs = process.argv[2] ? JSON.parse(readFileSync(process.argv[2], 'utf8')) : allSlugs();
+for (const slug of slugs) {
+  const file = source(slug);
+  if (!existsSync(file)) throw new Error(`No such icon: ${slug} (${file})`);
+  const target = join(OUT, `${slug}.svg`);
+  mkdirSync(dirname(target), { recursive: true });
+  copyFileSync(file, target);
+}
+console.log(`${slugs.length} icons in ${OUT}/`);
+```
+
+`icons.json` lists the slugs the app uses:
+
+```json
+["mi/baseline/email", "mi/baseline/send", "mdi/github", "mgg/abitazione-principale"]
+```
+
+```json
+"scripts": {
+  "icons": "node scripts/copy-icons.mjs icons.json",
+  "predev": "npm run icons",
+  "prebuild": "npm run icons"
+}
+```
+
+A slug that does not exist stops the script with an error. A slug used in the code but
+missing from `icons.json` gives a 404 at runtime: iconsauce avoids that by reading the
+sources. Without `icons.json` the script copies every icon of the three sets, all of
+them deployed: 18,720 files and 73 MB (`mi` 43 MB in five variants, `mdi` 29 MB, `mgg`
+1.3 MB).
+
+### Only the `mgg/` set
+
+An app that uses only Maggioli icons can copy the `svg-icons` folder, into `mgg/` under
+the served path: `@maggioli-design-system/svg-icons/dist/svg/` to `public/svg/mgg/`. With
+the Angular CLI that is an `assets` entry in `angular.json`:
+
+```json
+{ "glob": "**/*.svg", "input": "node_modules/@maggioli-design-system/svg-icons/dist/svg", "output": "/svg/mgg" }
+```
+
+### Tell mds-icon where the icons are
+
+Set the public URL of the folder the icons are served from, before the first `mds-icon`
+renders. Two ways:
 
 - `IconsSetService.setSvgPath('/svg/')`, imported from
-  `@maggioli-design-system/magma/services`: sets the path in code, without
-  `sessionStorage`, and reloads the icons already mounted
-- `mdsIcon.setSvgPath('/svg/')` - instance method on a temporary `mds-icon` node, after
-  `defineCustomElements()` has run
-- dispatch `new CustomEvent('mdsIconSvgPathUpdate')` on `window` to force a refresh
-  after changing the path
+  `@maggioli-design-system/magma/services` (recommended): sets the path in code, without
+  `sessionStorage`, and reloads the icons already mounted.
+- the `mdsIconSvgPath` key in `sessionStorage`, a one-liner the install tracks use. Some
+  browsers block storage (private windows, sandboxed iframes, storage partitioning): there
+  only `IconsSetService` works.
+
+```javascript
+import { IconsSetService } from '@maggioli-design-system/magma/services';
+
+IconsSetService.setSvgPath('/svg/');
+// or: window.sessionStorage.setItem('mdsIconSvgPath', '/svg/');
+```
+
+Icons mounted before a path set through `sessionStorage` reload on
+`window.dispatchEvent(new CustomEvent('mdsIconSvgPathUpdate'))`. Every option, with its
+snippet, is in the
+[`mds-icon` pattern](../../magma/dist/collection/components/mds-icon/pattern.md).
 
 Reference an icon by slug, never inline SVG and never import from an icon-set package:
 
@@ -190,14 +323,84 @@ Assets live under `@maggioli-design-system/identity/dist/`:
 - `dist/illustrations/`, `dist/products/` - additional brand imagery
 
 These are static read-only files - serve them like any other asset, do not modify
-them in the consumer project.
+them in the consumer project. `dist/identity.json` describes them: one entry per family of
+artworks, with its name as the artwork writes it, its owner and kind, and every variant with
+its path, form, colour, the background it is drawn for and its size. Read names and alt texts
+from it instead of from the file names, which lose accents and punctuation.
+
+## 5. Editor autocomplete
+
+Two halves, one extension each. Set them up in VS Code; for another editor, point its CSS
+custom property completion at the same `tokens.editor.css` and leave the rest to the user.
+
+| Completes | Extension | Fed by |
+| --------- | --------- | ------ |
+| Magma tokens inside `var(--...)`, in scale order, with a swatch on colors | CSS Var Complete (`phoenisx.cssvar`) | `@maggioli-design-system/styles/dist/css/tokens.editor.css`, every public token once |
+| Tailwind classes (`bg-surface-default`, `p-600`), with their value | Tailwind CSS IntelliSense (`bradlc.vscode-tailwindcss`), only if the app uses Tailwind | the CSS entry that imports Tailwind and Magma's theme (section 1) |
+
+MERGE these keys into `.vscode/settings.json` and `.vscode/extensions.json`: never overwrite
+a file that exists, the user's own settings stay.
+
+```json
+{
+  "cssvar.files": ["node_modules/@maggioli-design-system/styles/dist/css/tokens.editor.css"],
+  "cssvar.ignore": [],
+  "cssvar.disableSort": true
+}
+```
+
+```json
+{
+  "recommendations": ["phoenisx.cssvar", "bradlc.vscode-tailwindcss"],
+  "unwantedRecommendations": ["vunguyentuan.vscode-css-variables"]
+}
+```
+
+Leave `bradlc.vscode-tailwindcss` out of `recommendations` when the app has no Tailwind.
+
+The traps, all measured:
+
+- `cssvar.ignore` must be `[]`: its default, `["**/node_modules/**"]`, is applied over
+  `cssvar.files`, so the path above is dropped and nothing completes.
+- `cssvar.disableSort: true` keeps the order of the file (a scale from its smallest step
+  up); without it the list is alphabetical.
+- `vunguyentuan.vscode-css-variables` goes in `unwantedRecommendations`: it sorts
+  alphabetically, never opens the list by itself and duplicates every entry next to CSS
+  Var Complete.
+- Never import `tokens.editor.css` in the app: it is for editors only, and holds light
+  defaults that would freeze theming (it is wrapped in a query that never matches, so an
+  import does nothing at best).
+
+Tailwind IntelliSense finds the CSS entry on its own, the split imports of section 1
+included. Only if hovering a class shows nothing, add
+`"tailwindCSS.experimental.configFile": "<path of that CSS file>"`. If the app builds class
+names through functions (`clsx`, `cva`, `cn`), list the ones it uses in
+`"tailwindCSS.classFunctions"`, so the classes inside their calls complete too.
+
+Verify, after reloading the window:
+
+- in a CSS file, `var(--magma-surface` lists the surface roles, in order, with swatches;
+- with Tailwind, in markup: hovering `p-600` shows `1.5rem = 24px`, and `bg-surface-default`
+  shows a swatch in the completion list. No swatch on the semantic classes means an older
+  `@maggioli-design-system/styles`: update it.
+
+Known limits, nothing to configure:
+
+- Tailwind IntelliSense lists the utilities alphabetically, whatever the order of the
+  theme: `bg-surface-bisque-*` comes before `bg-surface-default`. Type the role name.
+- The class list offers Tailwind's stock spacing steps (`p-1` ... `p-96`), not Magma's:
+  with Magma's theme `p-1` is 0.04px. Write the Magma steps in full (`p-600`, `gap-400`):
+  they work and hover with their value, they are just not suggested.
 
 ## Checklist
 
 - [ ] `styles` + `design-tokens` installed on the matching version row
 - [ ] Global CSS imports in the exact cascade-layer order above
 - [ ] `@fontsource` fonts installed and imported in the `vendor` layer
-- [ ] `svg-icons` SVGs copied to a public path
+- [ ] Every icon slug the app uses served at `<mdsIconSvgPath><slug>.svg` (iconsauce or
+      the copy script, run before dev and build, output folder out of git)
 - [ ] `mdsIconSvgPath` set to that public path before hydration
 - [ ] (optional) `identity` installed if brand assets are used
 - [ ] Components registered per your target track
+- [ ] (VS Code) the editor keys merged into `.vscode/settings.json` and `extensions.json`;
+      `var(--magma-` completes, and with Tailwind `bg-surface-default` shows a swatch

package/agents/color.md

@@ -55,9 +55,11 @@ Tailwind names the TEXT roles `fg-*`, so a utility never reads `text-text-*`:
 `border-border-default`, `bg-accent-emphasis`, `bg-danger-wash-base`.
 
 Both faces need the setup in [`assets.md`](assets.md): the values come from
-`styles/dist/css/semantic.css` (without it every role paints nothing), the Tailwind
-utilities from `styles/dist/tailwind/theme.css`. A Tailwind modifier works as usual
-(`bg-surface-raised/80`).
+`styles/dist/css/semantic.css`, the Tailwind utilities from `styles/dist/tailwind/theme.css`.
+Without `semantic.css` a `var(--magma-*)` paints nothing, and a Tailwind utility paints the
+light default of its role, the fallback its bridge carries so editors can show a swatch: in
+dark mode, with a named theme or with more contrast it stays wrong, so the file is still
+required. A Tailwind modifier works as usual (`bg-surface-raised/80`).
 
 ## The roles
 
@@ -70,10 +72,10 @@ named theme retints all of it at once.
 | --- | --- | --- |
 | `surface-default` | `bg-surface-default` | the page canvas (the `body` already has it) |
 | `surface-raised` | `bg-surface-raised` | cards, panels, sticky headers |
-| `surface-overlay` | `bg-surface-overlay` | modal, dropdown, popover, sheet |
+| `surface-overlay` | `bg-surface-overlay` | modal, dropdown, popover, sheet, and anything lifted with a shadow |
 | `surface-sunken` | `bg-surface-sunken` | wells, insets, code blocks, tracks |
 | `surface-muted` | `bg-surface-muted` | same-plane grouping: zebra rows, a subtle section |
-| `wash-soft` / `wash-base` / `wash-strong` | `bg-wash-*` | a neutral pill or chip, by how marked it is |
+| `wash-soft` / `wash-base` / `wash-strong` | `bg-wash-*` | a flat neutral pill or chip (no shadow), by how marked it is |
 | `surface-inverse` / `surface-inverse-muted` | `bg-surface-inverse*` | the chip that flips with the mode (dark on a light UI) |
 | `on-inverse` | `text-on-inverse` | text and icons on either inverse level |
 | `text-default` | `text-fg-default` | body text, titles, primary data |

package/agents/components.md

@@ -3,7 +3,7 @@
   Source of truth: docs/agents/ in the magma monorepo.
   Regenerate with: npm run sync.agent-docs (from the stencil package).
 -->
-# Magma components catalogue (114 components)
+# Magma components catalogue (115 components)
 
 > Generated from each component's usage description. Each tag links the component's
 > own `AGENTS.md` (its API, with `pattern.md` and `antipattern.md` beside it) in
@@ -83,10 +83,10 @@
 | [`mds-pref-animation`](../../magma/dist/collection/components/mds-pref-animation/AGENTS.md) | The `<mds-pref-animation>` web component is a preference control that lets users choose how animations are presented (reduced, system-driven, or fully enabled) |
 | [`mds-pref-consumption`](../../magma/dist/collection/components/mds-pref-consumption/AGENTS.md) | The `<mds-pref-consumption>` web component is a preference control of the Magma Design System that lets the user pick an energy-consumption mode (`low`, `medium`, `high`); it is usually a child of `<mds-pref>` and renders as a tab group with one option per mode, so it has no native HTML primitive equivalent. |
 | [`mds-pref-contrast`](../../magma/dist/collection/components/mds-pref-contrast/AGENTS.md) | The `<mds-pref-contrast>` web component is a preference control that lets users switch the application's contrast mode (`more`, `system`, or `no-preference`) |
-| [`mds-pref-language`](../../magma/dist/collection/components/mds-pref-language/AGENTS.md) | The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, designed to be slotted inside `<mds-pref>` alongside the other preference children |
+| [`mds-pref-language`](../../magma/dist/collection/components/mds-pref-language/AGENTS.md) | The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, usually slotted inside the `<mds-pref>` panel alongside the other preference children |
 | [`mds-pref-language-item`](../../magma/dist/collection/components/mds-pref-language-item/AGENTS.md) | The `<mds-pref-language-item>` web component represents a single selectable language option inside the language-preference picker `<mds-pref-language>` |
-| [`mds-pref-mode`](../../magma/dist/collection/components/mds-pref-mode/AGENTS.md) | The `<mds-pref-mode>` web component is the mode preference control of the Magma Design System, designed to live as a direct child of `<mds-pref>` |
-| [`mds-pref-theme`](../../magma/dist/collection/components/mds-pref-theme/AGENTS.md) | The `<mds-pref-theme>` web component is the theme-switcher segment of the Magma accessibility preferences panel, designed to live as a direct child of `<mds-pref>` |
+| [`mds-pref-mode`](../../magma/dist/collection/components/mds-pref-mode/AGENTS.md) | The `<mds-pref-mode>` web component is the mode preference control of the Magma Design System, usually a direct child of the `<mds-pref>` panel |
+| [`mds-pref-theme`](../../magma/dist/collection/components/mds-pref-theme/AGENTS.md) | The `<mds-pref-theme>` web component is the theme-switcher segment of the Magma accessibility preferences panel, usually a direct child of `<mds-pref>` |
 | [`mds-pref-theme-item`](../../magma/dist/collection/components/mds-pref-theme-item/AGENTS.md) | The `<mds-pref-theme-item>` web component is a single selectable theme entry inside the `<mds-pref-theme>` preference picker |
 | [`mds-price-table`](../../magma/dist/collection/components/mds-price-table/AGENTS.md) | The `<mds-price-table>` web component is the layout container of the Magma Design System pricing-table family |
 | [`mds-price-table-features`](../../magma/dist/collection/components/mds-price-table-features/AGENTS.md) | The `<mds-price-table-features>` web component is the feature-matrix block of the Magma Design System pricing-table family |
@@ -120,6 +120,7 @@
 | [`mds-table-row`](../../magma/dist/collection/components/mds-table-row/AGENTS.md) | The `<mds-table-row>` web component represents a single data row inside a `<mds-table>` (slotted through `mds-table-body`; `mds-table-header` and `mds-table-footer` are rows themselves) |
 | [`mds-text`](../../magma/dist/collection/components/mds-text/AGENTS.md) | The `<mds-text>` web component is the foundational typography primitive of the Magma Design System |
 | [`mds-toast`](../../magma/dist/collection/components/mds-toast/AGENTS.md) | The `<mds-toast>` web component is the transient notification surface of the Magma Design System, used to surface brief, non-blocking feedback messages that appear over the viewport and auto-dismiss after a timeout |
+| [`mds-toast-region`](../../magma/dist/collection/components/mds-toast-region/AGENTS.md) | The `<mds-toast-region>` web component is the place where an application shows its toasts: placed once in the application shell, at an edge of the viewport, it lines up the `<mds-toast>` elements visible at the same time, each one readable, and announces them to assistive technologies |
 | [`mds-tooltip`](../../magma/dist/collection/components/mds-tooltip/AGENTS.md) | The `<mds-tooltip>` web component is the floating contextual hint of the Magma Design System |
 | [`mds-tree`](../../magma/dist/collection/components/mds-tree/AGENTS.md) | The `<mds-tree>` web component is the root container of the Magma Design System tree view, organizing a hierarchy of slotted `<mds-tree-item>` nodes into an expandable/collapsible structure |
 | [`mds-tree-item`](../../magma/dist/collection/components/mds-tree-item/AGENTS.md) | The `<mds-tree-item>` web component is the node primitive of the Magma Design System tree view: it represents a single labeled, expandable/collapsible entry inside an `<mds-tree>` and is also the recursive container for its own descendants |

package/agents/conventions.md

@@ -28,11 +28,27 @@
 
 - Boolean props default to `false`/`undefined`. Prefer removing the attribute over
   setting it to `false`.
+- A boolean attribute turns its prop on by being present. On the form-associated
+  components (`mds-button`, `mds-button-dropdown`, `mds-input`, `mds-input-date`,
+  `mds-input-date-range`, `mds-input-field`, `mds-input-otp`, `mds-input-range`,
+  `mds-input-select`, `mds-input-switch`, `mds-input-upload`) any value turns it on,
+  `"false"` included, as on a native control.
 - Disabled: `<mds-button disabled>`. Never `disabled="false"` - remove it instead. Set
   `disabled` on the component, not on a wrapper: disabled components are removed from
   the tab order automatically.
 - Async: `<mds-button await>` shows a spinner and blocks interaction; remove `await`
   (set `undefined`) when done.
+- From a framework, pass a real boolean to the property, not a string to the attribute:
+  - React with `magma-react`: `<MdsButton disabled={isDisabled} />` sets the property,
+    so `false` turns the prop off; the `.server` variants leave a `false` out of the
+    markup. A bare `mds-*` tag in React 18 JSX is different: React 18 writes
+    `disabled={false}` as the attribute `"false"`, which turns a form-associated component
+    on, so pass `undefined` there. React 19 sets the property and turns it off.
+  - Angular with `magma-angular`: bind the input, `[disabled]="isDisabled"`. The proxy
+    sets the property, so `false` turns the prop off. A static `disabled="false"` or an
+    attribute binding (`[attr.disabled]="false"`) writes the attribute instead, and turns
+    a form-associated component on; `[attr.disabled]="null"` removes it. Reactive Forms
+    `disable()` / `enable()` set the property through the value accessor.
 
 ## Sizing
 

package/agents/install.md

@@ -24,7 +24,7 @@ npm i @maggioli-design-system/magma-react @maggioli-design-system/magma
 matrix). Then install the assets from [`assets.md`](assets.md):
 
 ```bash
-npm i @maggioli-design-system/styles @maggioli-design-system/design-tokens @maggioli-design-system/svg-icons
+npm i @maggioli-design-system/styles @maggioli-design-system/design-tokens
 npm i @fontsource/karla @fontsource/merriweather @fontsource/roboto @fontsource/roboto-mono
 ```
 
@@ -116,9 +116,10 @@ export default function RootLayout({
 
 ## 4. Serve the icon SVGs and styles
 
-- Copy `@maggioli-design-system/svg-icons/dist/svg/` into the static folder served at
-  `/svg/` (Vite/CRA: `public/svg/`; Next.js: `public/svg/`). Match the path you pass
-  to `mdsIconSvgPath`.
+- Write the icons into the static folder served at `/svg/` (Vite and Next.js:
+  `public/svg/`) with one of the routes of [`assets.md`](assets.md) section 3
+  (iconsauce or the copy script, run from `predev` and `prebuild`). Match the path you
+  pass to `mdsIconSvgPath`.
 - Import the global CSS block from [`assets.md`](assets.md) in your global stylesheet
   (`app/globals.css`, `src/index.css`, ...) so the cascade-layer order is preserved.
 
@@ -164,7 +165,7 @@ SSR notes:
 - Icons render empty server-side (the box is reserved, no layout shift) and the
   default theme is rendered - see the SSR section in
   [`install.md`](install.md).
-- The hydrate module (`magma/hydrate`) bundles all 114 components (~3 MB,
+- The hydrate module (`magma/hydrate`) bundles all 115 components (~3 MB,
   server-only). It is imported lazily behind a `typeof window` check and must
   never end up in a client bundle.
 
@@ -208,6 +209,11 @@ With React Router the handler is `(href) => navigate(href)` from `useNavigate()`
   on the client - use the `.server` variants (section 5) to get real SSR markup.
 - Keep `magma` and `magma-react` on the exact same version; the wrapper is generated
   against a specific `magma` build.
+- Pass booleans as booleans: `<MdsButton disabled={false} />` sets the property and turns
+  the prop off, and the `.server` variants leave a `false` out of the markup. Render the
+  wrapper, not the bare `mds-*` tag: in React 18 JSX `<mds-button disabled={false}>`
+  writes the attribute `"false"`, which turns a form-associated component on (see
+  [`conventions.md`](conventions.md)).
 
 ## See also
 

package/agents/reporting.md

@@ -56,8 +56,11 @@ gh label list --repo magma-design-system/magma --search prd-
 
 Match it against this project's repository name (the `origin` remote, or the `name` in
 `package.json`). If none matches, do not create one: the Magma maintainers manage the
-labels of their repository. Open the issue without it and say in the body which project
-and repository it comes from, so they can add the label.
+labels of their repository, and a label missing from their configuration is deleted by
+the next sync. Open the issue without it, and propose its name in the body, so the
+maintainers add it as it is: `prd-` and the project's short name, lowercase, in
+kebab-case (`prd-mindy` for `mindy-webapp`, `prd-docs` for the docs site). Leave out
+generic words such as `app`, `webapp`, `frontend` or the organization's name.
 
 GitHub sets labels on a new issue only for users with write access to the repository,
 and drops them for everyone else, often without an error. After creating the issue,
@@ -98,6 +101,12 @@ What the project does meanwhile, if anything.
 Found in <project> (<repository>): <where in the app>.
 ```
 
+When step 4 found no origin label, end the body with the one you propose:
+
+```markdown
+No origin label for this project yet: proposed `prd-<name>`.
+```
+
 Read the installed versions from the lockfile or `npm ls`, not from the ranges in
 `package.json`.
 

package/agents/theming.md

@@ -138,3 +138,18 @@ by itself changes the shape WITHOUT the scale.
 In your own CSS take radii from the `--magma-radius-*` scale (`none`, `3xs` ... `5xl`,
 `full`), which follows the axis: `border-radius: var(--magma-radius-lg)`. A raw
 `--radius-*` token or a pixel value stays the same under every shape.
+
+A browser without `corner-shape` (Firefox, Safari) gets round corners and the round
+scale on its own. A control of your own whose radius is past half its height
+(Chromium clamps it to half the height) needs one more step to keep its look there:
+cap the radius at a part of its height, as Magma's buttons and fields do.
+
+```css
+.my-control {
+  --my-control-height: 2.25rem;
+
+  border-radius: min(var(--magma-radius-2xl), var(--magma-corner-cap) * var(--my-control-height));
+  corner-shape: var(--magma-corner-shape);
+  min-height: var(--my-control-height);
+}
+```

package/dist/components.js

@@ -109,6 +109,7 @@ export { MdsTableHeader } from "./mds-table-header.js";
 export { MdsTableRow } from "./mds-table-row.js";
 export { MdsTable } from "./mds-table.js";
 export { MdsText } from "./mds-text.js";
+export { MdsToastRegion } from "./mds-toast-region.js";
 export { MdsToast } from "./mds-toast.js";
 export { MdsTooltip } from "./mds-tooltip.js";
 export { MdsTreeItem } from "./mds-tree-item.js";

package/dist/components.server.js

@@ -109,6 +109,7 @@ export { MdsTableHeader } from "./mds-table-header.server.js";
 export { MdsTableRow } from "./mds-table-row.server.js";
 export { MdsTable } from "./mds-table.server.js";
 export { MdsText } from "./mds-text.server.js";
+export { MdsToastRegion } from "./mds-toast-region.server.js";
 export { MdsToast } from "./mds-toast.server.js";
 export { MdsTooltip } from "./mds-tooltip.server.js";
 export { MdsTreeItem } from "./mds-tree-item.server.js";

package/dist/mds-input-date-range.server.js

@@ -12,6 +12,7 @@ export const MdsInputDateRange = /*@__PURE__*/ createComponent({
         min: 'min',
         max: 'max',
         delay: 'delay',
+        size: 'size',
         hideToday: 'hide-today',
         dualCalendar: 'dual-calendar',
         name: 'name',

package/dist/mds-input-date.server.js

@@ -13,6 +13,7 @@ export const MdsInputDate = /*@__PURE__*/ createComponent({
         min: 'min',
         max: 'max',
         delay: 'delay',
+        size: 'size',
         hideToday: 'hide-today',
         disabled: 'disabled',
         readonly: 'readonly',

package/dist/mds-input-select.server.js

@@ -14,6 +14,7 @@ export const MdsInputSelect = /*@__PURE__*/ createComponent({
         disabled: 'disabled',
         required: 'required',
         multiple: 'multiple',
+        rows: 'rows',
         size: 'size',
         value: 'value',
         defaultValue: 'default-value',

package/dist/mds-input.server.js

@@ -26,6 +26,7 @@ export const MdsInput = /*@__PURE__*/ createComponent({
         required: 'required',
         variant: 'variant',
         tip: 'tip',
+        size: 'size',
         step: 'step',
         type: 'type',
         typography: 'typography',

package/dist/mds-table-footer.server.js

@@ -5,7 +5,7 @@ import * as clientComponents from "@maggioli-design-system/magma-react";
 export const serializeShadowRoot = "declarative-shadow-dom";
 export const MdsTableFooter = /*@__PURE__*/ createComponent({
     tagName: 'mds-table-footer',
-    properties: {},
+    properties: { selectable: 'selectable' },
     hydrateModule: typeof window === 'undefined' ? import('@maggioli-design-system/magma/hydrate') : undefined,
     clientModule: clientComponents.MdsTableFooter,
     serializeShadowRoot

package/dist/mds-table-header-cell.js

@@ -7,6 +7,6 @@ export const MdsTableHeaderCell = /*@__PURE__*/ createComponent({
     elementClass: MdsTableHeaderCellElement,
     // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
     react: React,
-    events: {},
+    events: { onMdsTableHeaderCellSort: 'mdsTableHeaderCellSort' },
     defineCustomElement: defineMdsTableHeaderCell
 });

package/dist/mds-table-header-cell.server.js

@@ -8,6 +8,7 @@ export const MdsTableHeaderCell = /*@__PURE__*/ createComponent({
     properties: {
         sortable: 'sortable',
         label: 'label',
+        sortKey: 'sort-key',
         direction: 'direction'
     },
     hydrateModule: typeof window === 'undefined' ? import('@maggioli-design-system/magma/hydrate') : undefined,

package/dist/mds-table.server.js

@@ -8,7 +8,8 @@ export const MdsTable = /*@__PURE__*/ createComponent({
     properties: {
         interactive: 'interactive',
         selectable: 'selectable',
-        selection: 'selection'
+        selection: 'selection',
+        sorting: 'sorting'
     },
     hydrateModule: typeof window === 'undefined' ? import('@maggioli-design-system/magma/hydrate') : undefined,
     clientModule: clientComponents.MdsTable,

package/dist/mds-toast-region.js

@@ -0,0 +1,12 @@
+'use client';
+import { createComponent } from '@stencil/react-output-target/runtime';
+import React from 'react';
+import { MdsToastRegion as MdsToastRegionElement, defineCustomElement as defineMdsToastRegion } from "@maggioli-design-system/magma/dist/components/mds-toast-region.js";
+export const MdsToastRegion = /*@__PURE__*/ createComponent({
+    tagName: 'mds-toast-region',
+    elementClass: MdsToastRegionElement,
+    // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
+    react: React,
+    events: {},
+    defineCustomElement: defineMdsToastRegion
+});