@maggioli-design-system/magma-angular 2.0.0-beta.2 → 2.0.0-beta.3

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.
Files changed (10) hide show
  1. package/AGENTS.md +60 -0
  2. package/README.md +11 -0
  3. package/agents/assets.md +180 -0
  4. package/agents/components.md +128 -0
  5. package/agents/install.md +132 -0
  6. package/agents/usage.md +211 -0
  7. package/fesm2022/maggioli-design-system-magma-angular.mjs +105 -80
  8. package/fesm2022/maggioli-design-system-magma-angular.mjs.map +1 -1
  9. package/index.d.ts +71 -50
  10. package/package.json +2 -2
package/AGENTS.md ADDED
@@ -0,0 +1,60 @@
1
+ <!--
2
+ GENERATED FILE - do not edit by hand.
3
+ Source of truth: docs/agents/ in the magma monorepo.
4
+ Regenerate with: npm run sync.agent-docs (from the stencil package).
5
+ -->
6
+ # @maggioli-design-system/magma-angular - agent install guide
7
+
8
+ > Version 2.0.0-beta.3. You (the agent) are installing Magma into THIS project. Do not
9
+ > assume the setup - detect it from the project, then ask the user only for what you
10
+ > cannot infer. The detailed steps live in [`agents/install.md`](agents/install.md)
11
+ > (this target) and [`agents/assets.md`](agents/assets.md) (shared styles, fonts,
12
+ > icons). This package targets: **Angular (>= 18.2)**.
13
+
14
+ ## Step 1 - detect (read, do not ask)
15
+
16
+ Inspect the consumer project before asking anything:
17
+
18
+ | What | Where to look |
19
+ | ---- | ------------- |
20
+ | Framework | `package.json` deps: `@angular/core` -> Angular, `react`/`next` -> React, else vanilla |
21
+ | Magma wrapper installed | presence of `magma-angular` / `magma-react` / `magma` in deps |
22
+ | Bundler / static dir | `angular.json` (Angular CLI assets), `vite.config.*`, `next.config.*` (`public/`), webpack |
23
+ | Tailwind + version | `tailwindcss` in deps (v3 vs v4 -> different preset) |
24
+ | SSR | `@angular/ssr` / Angular Universal, or Next App Router |
25
+ | Compatible versions | derive from the installed `@maggioli-design-system/magma` major (see matrix in install.md) |
26
+
27
+ ## Step 2 - ask only the gaps
28
+
29
+ Ask the user only what detection left undecided. Typical questions:
30
+
31
+ 1. **Icons**: use the prebuilt set (`@maggioli-design-system/svg-icons`) or do you need
32
+ **iconsauce** for tree-shaking / custom icons? Most consumers do NOT need iconsauce -
33
+ Magma already ships resolved SVGs; iconsauce is an internal build dependency. Only
34
+ add `@iconsauce/*` if the user wants their own icon pipeline.
35
+ 2. **Static assets path**: where are static files served from? This sets `mdsIconSvgPath`
36
+ and the SVG copy destination.
37
+ 3. **Dark mode / preferences**: needed? If yes, wire the preference classes and components.
38
+ 4. Confirm the version row if the installed major is ambiguous.
39
+
40
+ ## Step 3 - execute
41
+
42
+ 1. Install packages and the shared assets - see [`agents/install.md`](agents/install.md).
43
+ 2. Wire styles in the exact cascade-layer order - see [`agents/assets.md`](agents/assets.md).
44
+ 3. Copy the icon SVGs to the static path and set `mdsIconSvgPath`.
45
+ 4. Register components: MagmaModule.forRoot() from '@maggioli-design-system/magma-angular'.
46
+
47
+ ## Step 4 - verify
48
+
49
+ Build the app and confirm an `mds-*` component renders and at least one icon loads from
50
+ the configured path. Report what was installed, the cascade order used, and the icon path.
51
+
52
+ ## Using the components
53
+
54
+ Once installed, do not guess component APIs - read what ships with the package:
55
+
56
+ - [`agents/usage.md`](agents/usage.md) - conventions (tone/variant, events, slots,
57
+ compound, icons, a11y) and app-level styling (token classes, typography, dark mode).
58
+ - [`agents/components.md`](agents/components.md) - the catalogue: which component to reach for.
59
+ - `@maggioli-design-system/magma/dist/documentation.json` - full per-component props,
60
+ events, slots, CSS vars and usage. `dist/types/components.d.ts` drives editor IntelliSense.
package/README.md CHANGED
@@ -2,6 +2,17 @@
2
2
 
3
3
  Magma Angular specific building blocks on top of [@maggioli-design-system/magma](https://www.npmjs.com/package/@maggioli-design-system/magma) components.
4
4
 
5
+ ## Install with an AI agent
6
+
7
+ This package ships an agent-readable install guide, versioned with the package. Point
8
+ your coding agent (Claude Code, etc.) at it and let it wire up styles, fonts, icons and
9
+ component registration, asking you only for what it cannot detect from your project:
10
+
11
+ > Read `node_modules/@maggioli-design-system/magma-angular/AGENTS.md` and follow it to
12
+ > install Magma into this project.
13
+
14
+ The detailed steps live under `agents/` in this package.
15
+
5
16
  ## Compatibility
6
17
 
7
18
  `magma-angular` follows the same major version as `magma`. Use the versions of `@maggioli-design-system/design-tokens` and `@maggioli-design-system/styles` matching your magma major version:
package/agents/assets.md ADDED
@@ -0,0 +1,180 @@
1
+ <!--
2
+ GENERATED FILE - do not edit by hand.
3
+ Source of truth: docs/agents/ in the magma monorepo.
4
+ Regenerate with: npm run sync.agent-docs (from the stencil package).
5
+ -->
6
+ # install assets.md
7
+
8
+ ## Purpose
9
+
10
+ Canonical setup for the assets every Magma consumer needs, **identical for all three
11
+ targets** (web components, React, Angular): styles, fonts, icons and optional brand
12
+ identity. The per-target tracks ([`install.md`](install.md)) link here instead of repeating
13
+ this. If something about styles/fonts/icons setup is unclear, this file wins.
14
+
15
+ For the deeper styles reference (Tailwind config, color classes, typography
16
+ utilities, dark mode, `--magma-*` global vars) see
17
+ the Magma styles guide. This file is the
18
+ minimum to get a consumer running.
19
+
20
+ ## 1. Styles
21
+
22
+ ### Packages
23
+
24
+ ```bash
25
+ npm i @maggioli-design-system/styles @maggioli-design-system/design-tokens
26
+ ```
27
+
28
+ Pin both to the row matching your `magma` major (see [`AGENTS.md`](../AGENTS.md) matrix).
29
+
30
+ ### Import order (mandatory)
31
+
32
+ Magma styles rely on a fixed cascade-layer order. Import them in exactly this order
33
+ in your global CSS entry point, or specificity conflicts and dark mode will break:
34
+
35
+ ```css
36
+ @layer reset, vendor, theme, base, components, utilities, overrides;
37
+ /* or @import '@maggioli-design-system/styles/dist/css/layer.css'; */
38
+
39
+ @import 'normalize.css' layer(reset);
40
+
41
+ /* Fonts - see section 2 */
42
+ @import '@fontsource/karla/400.css' layer(vendor);
43
+ @import '@fontsource/karla/700.css' layer(vendor);
44
+ @import '@fontsource/merriweather/400.css' layer(vendor);
45
+ @import '@fontsource/merriweather/700.css' layer(vendor);
46
+ @import '@fontsource/roboto/500.css' layer(vendor);
47
+ @import '@fontsource/roboto/700.css' layer(vendor);
48
+ @import '@fontsource/roboto-mono/400.css' layer(vendor);
49
+
50
+ /* Magma styles */
51
+ @import '@maggioli-design-system/styles/dist/css/colors-rgb.css' layer(theme);
52
+ @import '@maggioli-design-system/styles/dist/css/reset.css' layer(reset);
53
+ @import '@maggioli-design-system/styles/dist/css/hydrated.css' layer(base);
54
+ @import '@maggioli-design-system/styles/dist/css/transitions.css' layer(base);
55
+ @import '@maggioli-design-system/styles/dist/css/animations.css' layer(base);
56
+ @import '@maggioli-design-system/styles/dist/css/globals.css' layer(theme);
57
+ @import '@maggioli-design-system/styles/dist/css/base.css' layer(base);
58
+
59
+ /* your Tailwind entry point, if any */
60
+ @import './tailwind.css';
61
+ ```
62
+
63
+ What each file provides:
64
+
65
+ | File | Purpose |
66
+ | ---- | ------- |
67
+ | `colors-rgb.css` | RGB color tokens (`--tone-*`, `--status-*`, ...). Required by components and Tailwind. Also redefines tokens for dark / high-contrast |
68
+ | `reset.css` | Opinionated CSS reset |
69
+ | `hydrated.css` | Anti-FOUC for Stencil - hides components until hydrated |
70
+ | `transitions.css`, `animations.css` | Shared motion |
71
+ | `globals.css` | Global `--magma-*` design decisions |
72
+ | `base.css` | Base element styles (sets `--font-info` body font, etc.) |
73
+
74
+ DO NOT import `colors-hex-*.css` when using components or Tailwind - they cannot be
75
+ used with opacity modifiers and bypass dark mode. Use `colors-rgb.css`.
76
+
77
+ ### Tailwind (optional)
78
+
79
+ If the consumer uses Tailwind, extend Magma's preset:
80
+
81
+ ```javascript
82
+ // tailwind.config.js
83
+ module.exports = {
84
+ content: ['./src/**/*.{ts,tsx,html}'],
85
+ presets: [require('@maggioli-design-system/styles')],
86
+ };
87
+ ```
88
+
89
+ Tailwind 3 layers are also published under
90
+ `@maggioli-design-system/styles/dist/tailwind3/`.
91
+
92
+ ## 2. Fonts
93
+
94
+ Magma does NOT bundle webfonts. The typography tokens point to **Roboto** (title),
95
+ **Karla** (info / UI), **Merriweather** (read / editorial) and **Roboto Mono**
96
+ (code), each with a system fallback. The consumer must load the actual fonts, easiest
97
+ via [`@fontsource`](https://fontsource.org/):
98
+
99
+ ```bash
100
+ npm i @fontsource/karla @fontsource/merriweather @fontsource/roboto @fontsource/roboto-mono
101
+ ```
102
+
103
+ The `@import` lines are already in the section 1 block (under `layer(vendor)`). The
104
+ weights listed (Karla 400/700, Merriweather 400/700, Roboto 500/700, Roboto Mono 400)
105
+ are the minimum used by the type scale; add more weights as needed.
106
+
107
+ Self-hosting via `@fontsource` is preferred over a CDN `<link>` so the fonts respect
108
+ the `vendor` cascade layer and ship offline.
109
+
110
+ ## 3. Icons
111
+
112
+ Icons are managed by **iconsauce** and consumed at runtime by `mds-icon`, which
113
+ fetches each icon as an SVG file from a path the host app configures. See the icons
114
+ section in the Magma component conventions guide for how
115
+ slugs resolve; this section is only the consumer-side wiring.
116
+
117
+ ### Package and asset copy
118
+
119
+ ```bash
120
+ npm i @maggioli-design-system/svg-icons
121
+ ```
122
+
123
+ Copy the SVG library to a publicly served path. The package ships the files under
124
+ `@maggioli-design-system/svg-icons/dist/svg/`. Copy them to e.g. `public/svg/` (the
125
+ mechanism depends on the bundler - see each track file).
126
+
127
+ ### Tell mds-icon where the icons are
128
+
129
+ The simplest way: set `mdsIconSvgPath` in `sessionStorage` before components hydrate.
130
+ The value is the public URL of the folder you copied the SVGs into:
131
+
132
+ ```javascript
133
+ window.sessionStorage.setItem('mdsIconSvgPath', '/svg/');
134
+ ```
135
+
136
+ Alternatives (after `defineCustomElements()` has run), documented in
137
+ the mds-icon readme:
138
+
139
+ - `mdsIcon.setSvgPath('/svg/')` - instance method on a temporary `mds-icon` node
140
+ - `MdsIcon.setSvgPathStatic('/svg/')` - static class method
141
+ - dispatch `new CustomEvent('mdsIconSvgPathUpdate')` on `window` to force a refresh
142
+ after changing the path
143
+
144
+ Reference an icon by slug, never inline SVG and never import from an icon-set package:
145
+
146
+ ```html
147
+ <mds-icon name="action-email-send"></mds-icon>
148
+ <mds-button icon="action-email-send">Send</mds-button>
149
+ ```
150
+
151
+ The mgg-icons webfont (`@maggioli-design-system/icons`) is an alternative output and
152
+ is NOT used by Magma at runtime - prefer the SVG-file strategy above.
153
+
154
+ ## 4. Identity / brand (optional)
155
+
156
+ Logos and avatars for Maggioli Group products. Install only if the app renders brand
157
+ assets:
158
+
159
+ ```bash
160
+ npm i @maggioli-design-system/identity
161
+ ```
162
+
163
+ Assets live under `@maggioli-design-system/identity/dist/`:
164
+
165
+ - `dist/brand/` - logos per brand (gruppo-maggioli, maggioli-editore, rnd, ...)
166
+ - `dist/avatar/` - avatar illustrations (svg / webp / png / pdf)
167
+ - `dist/illustrations/`, `dist/products/` - additional brand imagery
168
+
169
+ These are static read-only files - serve them like any other asset, do not modify
170
+ them in the consumer project.
171
+
172
+ ## Checklist
173
+
174
+ - [ ] `styles` + `design-tokens` installed on the matching version row
175
+ - [ ] Global CSS imports in the exact cascade-layer order above
176
+ - [ ] `@fontsource` fonts installed and imported in the `vendor` layer
177
+ - [ ] `svg-icons` SVGs copied to a public path
178
+ - [ ] `mdsIconSvgPath` set to that public path before hydration
179
+ - [ ] (optional) `identity` installed if brand assets are used
180
+ - [ ] Components registered per your target track
package/agents/components.md ADDED
@@ -0,0 +1,128 @@
1
+ <!--
2
+ GENERATED FILE - do not edit by hand.
3
+ Source of truth: docs/agents/ in the magma monorepo.
4
+ Regenerate with: npm run sync.agent-docs (from the stencil package).
5
+ -->
6
+ # Magma components catalogue (114 components)
7
+
8
+ > Generated from each component's usage description. For a component's full props /
9
+ > events / slots / CSS vars read `@maggioli-design-system/magma/dist/documentation.json`
10
+ > or the types in `dist/types/components.d.ts`; for conventions and styling read
11
+ > [`usage.md`](usage.md).
12
+
13
+ | Component | What it is |
14
+ | --------- | ---------- |
15
+ | `mds-accordion` | The `<mds-accordion>` web component is the compound container of the Magma Design System that groups and orchestrates a set of collapsible `<mds-accordion-item>` panels |
16
+ | `mds-accordion-item` | The `<mds-accordion-item>` web component is a single collapsible panel of the Magma Design System, designed to be slotted inside its parent `<mds-accordion>` |
17
+ | `mds-accordion-timer` | The `<mds-accordion-timer>` web component is the orchestrating parent of an auto-advancing accordion in the Magma Design System |
18
+ | `mds-accordion-timer-item` | The `<mds-accordion-timer-item>` web component is the single collapsible panel of a timed, auto-advancing accordion, designed to live exclusively inside its parent `<mds-accordion-timer>` |
19
+ | `mds-author` | The `<mds-author>` web component is the layout primitive of the Magma Design System for presenting a person's identity: it pairs an avatar with author information (name, role, or any related details) |
20
+ | `mds-avatar` | The `<mds-avatar>` web component renders a compact, circular representation of a user or entity in the Magma Design System |
21
+ | `mds-avatar-stack` | The `<mds-avatar-stack>` web component groups a set of overlapping `<mds-avatar-stack-item>` children into a single horizontal cluster, the Magma Design System pattern for showing the people associated with an entity (assignees, participants, collaborators) in a compact, space-saving row. |
22
+ | `mds-avatar-stack-item` | The `<mds-avatar-stack-item>` web component is a compound child that represents a single avatar inside an `<mds-avatar-stack>`, wrapping an internal `<mds-avatar>` so individual avatars can be overlapped, sized, and counted as a group rather than rendered standalone. |
23
+ | `mds-badge` | The `<mds-badge>` web component is the Magma Design System's compact status and label indicator, used to attach a short categorical signal (count, state, tag) to other content |
24
+ | `mds-banner` | The `<mds-banner>` web component is the Magma Design System surface for contextual, in-page messages - informational notices, status callouts, and alerts - pairing an optional icon, headline, body text, and inline actions inside a single themed box. |
25
+ | `mds-benchmark-bar` | The `<mds-benchmark-bar>` web component is a read-only data-visualization element of the Magma Design System that pairs a labelled caption with a horizontal progress bar to express a single benchmark value on a 0-100 scale |
26
+ | `mds-bibliography` | The `<mds-bibliography>` web component renders a single citation entry formatted according to a recognized academic style |
27
+ | `mds-breadcrumb` | The `<mds-breadcrumb>` web component is the navigation-trail container of the Magma Design System |
28
+ | `mds-breadcrumb-item` | The `<mds-breadcrumb-item>` web component represents a single navigable depth in a breadcrumb trail |
29
+ | `mds-button` | The `<mds-button>` web component is the primary interactive action control of the Magma Design System |
30
+ | `mds-button-dropdown` | The `<mds-button-dropdown>` web component is a split-button control of the Magma Design System: it pairs a primary `<mds-button>` action with a secondary chevron button that opens an attached `<mds-dropdown>`, giving users a default action plus a menu of related choices in a single, visually unified control. |
31
+ | `mds-button-group` | The `<mds-button-group>` web component is a layout container of the Magma Design System that clusters related `<mds-button>` controls into a single, evenly-spaced horizontal group such as toolbars, action bars, or segmented sets of actions |
32
+ | `mds-calendar` | The `<mds-calendar>` web component is the date-selection surface of the Magma Design System: a localized month grid that lets users pick either a single day or a date range |
33
+ | `mds-calendar-cell` | The `<mds-calendar-cell>` web component represents a single selectable day inside the `<mds-calendar>` grid |
34
+ | `mds-card` | The `<mds-card>` web component is the surface container of the Magma Design System: a styled, self-contained panel that groups related media, heading, body and action content into a single bounded region |
35
+ | `mds-card-content` | The `<mds-card-content>` web component is the body region of a `<mds-card>`, grouping the primary textual or component content of a card |
36
+ | `mds-card-footer` | The `<mds-card-footer>` web component is the footer region of a `<mds-card>`, grouping the trailing content of a card (typically actions such as buttons or supplementary metadata) into the card's bottom region. |
37
+ | `mds-card-header` | The `<mds-card-header>` web component is the header region of a `<mds-card>`, grouping the card's title, supporting text, and optional inline actions |
38
+ | `mds-card-media` | The `<mds-card-media>` web component is the media region of a `<mds-card>`: it wraps an image, video or other visual asset and provides an optional overlay layer for text or controls rendered on top of that asset |
39
+ | `mds-chip` | The `<mds-chip>` web component is the Magma Design System's compact element for representing a discrete piece of information, a filter, a selection, or a removable token |
40
+ | `mds-details` | The `<mds-details>` web component is the disclosure widget of the Magma Design System: a collapsible block with a clickable header that shows or hides its content on demand |
41
+ | `mds-dropdown` | The `<mds-dropdown>` web component is a floating overlay surface of the Magma Design System that anchors arbitrary slotted content next to an external trigger element |
42
+ | `mds-emoji` | The `<mds-emoji>` web component renders one of the Magma Design System's animated mascot illustrations (`mia` or `simi`) as an interactive SVG |
43
+ | `mds-entity` | The `<mds-entity>` web component represents a person, organization, or resource as a compact identity block in the Magma Design System, pairing an avatar with a name, optional secondary details, and contextual actions |
44
+ | `mds-file` | The `<mds-file>` web component is the Magma Design System control for representing a downloadable file as a rich, clickable card |
45
+ | `mds-file-preview` | The `<mds-file-preview>` web component is the Magma Design System card that previews an uploaded or referenced file, surfacing its name, size, type, and a format-aware icon or thumbnail |
46
+ | `mds-filter` | The `<mds-filter>` web component is a compound container that groups a set of `<mds-filter-item>` chips into a single, scrollable filter bar, coordinating their selection state and exposing the active values as one combined change event |
47
+ | `mds-filter-item` | The `<mds-filter-item>` web component is a single selectable option inside the `<mds-filter>` container of the Magma Design System |
48
+ | `mds-header` | The `<mds-header>` web component is the top-level page header container of the Magma Design System |
49
+ | `mds-header-bar` | The `<mds-header-bar>` web component is the top bar of a Magma application layout: it holds the product branding on the left and the primary navigation actions on the right, collapsing those actions into a hamburger menu on smaller viewports |
50
+ | `mds-help` | The `<mds-help>` web component is a contextual help affordance of the Magma Design System: a small help icon that reveals an explanatory tooltip on interaction |
51
+ | `mds-horizontal-scroll` | The `<mds-horizontal-scroll>` web component is a horizontally scrolling container of the Magma Design System |
52
+ | `mds-hr` | The `<mds-hr>` web component is the horizontal rule of the Magma Design System |
53
+ | `mds-icon` | The `<mds-icon>` web component is the single glyph primitive of the Magma Design System: it inlines an SVG into the DOM so the artwork inherits color and sizing from CSS, and it is the building block that nearly every other component (button, chip, input, banner, list-item, etc.) composes to render its iconography |
54
+ | `mds-img` | The `<mds-img>` web component is the responsive image primitive of the Magma Design System |
55
+ | `mds-input` | The `<mds-input>` web component is the primary single- and multi-line text entry control of the Magma Design System |
56
+ | `mds-input-date` | The `<mds-input-date>` web component is the Magma Design System control for capturing a single calendar date |
57
+ | `mds-input-date-range` | The `<mds-input-date-range>` web component is the Magma Design System control for capturing a start/end date pair, composing two slotted `<mds-input-date>` fields with a shared pop-up `mds-calendar` (in range-picker mode) and optional quick-pick presets |
58
+ | `mds-input-date-range-preselection` | The `<mds-input-date-range-preselection>` web component is a compound child of `<mds-input-date-range>` |
59
+ | `mds-input-field` | The `<mds-input-field>` web component is the form-field wrapper of the Magma Design System |
60
+ | `mds-input-otp` | The `<mds-input-otp>` web component is the Magma Design System control for entering one-time passcodes, rendering a row of single-digit fields that together compose a single form value |
61
+ | `mds-input-range` | The `<mds-input-range>` web component is the Magma Design System slider control for picking a single numeric value from a continuous interval |
62
+ | `mds-input-select` | The `<mds-input-select>` web component is the Magma Design System single- and multi-choice dropdown control |
63
+ | `mds-input-switch` | The `<mds-input-switch>` web component is the binary/selectable input control of the Magma Design System |
64
+ | `mds-input-tip` | The `<mds-input-tip>` web component is the floating helper container of the Magma Design System input family: it overlays an input field and reveals supplementary content (slotted `mds-input-tip-item` chips, hints, or actions) that expands when the field becomes active |
65
+ | `mds-input-tip-item` | The `<mds-input-tip-item>` web component is a single contextual hint row rendered inside the `<mds-input-tip>` container |
66
+ | `mds-input-upload` | The `<mds-input-upload>` web component is the Magma Design System file-upload control |
67
+ | `mds-keyboard` | The `<mds-keyboard>` web component renders a keyboard shortcut as a row of physical-looking keycaps, acting as the compound parent for one or more slotted `<mds-keyboard-key>` children |
68
+ | `mds-keyboard-key` | The `<mds-keyboard-key>` web component renders a single physical-looking keycap inside a `<mds-keyboard>` parent, supplying the visual unit for one key of a shortcut combination (e.g |
69
+ | `mds-kpi` | The `<mds-kpi>` web component is the layout container of the Magma Design System for presenting groups of key performance indicators |
70
+ | `mds-kpi-item` | The `<mds-kpi-item>` web component is a compound child that represents a single key-performance-indicator entry - a prominent numeric `label` with an optional `description` and `icon` - inside its parent container `<mds-kpi>` |
71
+ | `mds-label` | The `<mds-label>` web component is the Magma Design System tag/chip used to display a short, non-interactive piece of text such as a status, a category, or a removable selection. |
72
+ | `mds-list` | The `<mds-list>` web component is the structural container of the Magma Design System list family |
73
+ | `mds-list-item` | The `<mds-list-item>` web component is the single entry of a Magma list, designed to be slotted exclusively inside its parent `<mds-list>` |
74
+ | `mds-mention` | The `<mds-mention>` web component renders a compact inline chip that references a person or entity - the kind of token produced when you type `@name` in an editor or comment field |
75
+ | `mds-modal` | The `<mds-modal>` web component is the Magma Design System overlay container for dialogs, presenting content in a windowed surface layered above the page with an optional backdrop |
76
+ | `mds-note` | The `<mds-note>` web component is the annotation surface of the Magma Design System: a short, colored sticky-note block used to attach a remark, reminder, or callout to surrounding content |
77
+ | `mds-notification` | The `<mds-notification>` web component is a numeric badge/dot indicator of the Magma Design System that attaches to another element (an icon, a button, an avatar) to signal a count of pending items |
78
+ | `mds-paginator` | The `<mds-paginator>` web component is the page-navigation control of the Magma Design System |
79
+ | `mds-paginator-item` | The `<mds-paginator-item>` web component is a compound child of `<mds-paginator>` that renders a single clickable cell of the pagination control: either a numbered page or a navigation arrow |
80
+ | `mds-policy-ai` | The `<mds-policy-ai>` web component is the Magma Design System disclosure marker that flags AI-generated content as produced by MIA (Maggioli's artificial intelligence) and links to the official AI usage policy |
81
+ | `mds-pref` | The `<mds-pref>` web component is the accessibility-preferences panel of the Magma Design System: a compound parent that groups user-facing settings (animation, consumption, contrast, theme, language) so people can tune readability, motion, and language for their session |
82
+ | `mds-pref-animation` | The `<mds-pref-animation>` web component is a preference control that lets users choose how animations are presented (reduced, system-driven, or fully enabled) |
83
+ | `mds-pref-consumption` | 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 a compound child of `<mds-pref>` and renders as a tab group with one option per mode, so it has no native HTML primitive equivalent. |
84
+ | `mds-pref-contrast` | The `<mds-pref-contrast>` web component is a preference control that lets users switch the application's contrast mode (`more`, `system`, or `no-preference`) |
85
+ | `mds-pref-language` | 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 |
86
+ | `mds-pref-language-item` | The `<mds-pref-language-item>` web component represents a single selectable language option inside the language-preference picker `<mds-pref-language>` |
87
+ | `mds-pref-theme` | The `<mds-pref-theme>` web component is the theme-mode preference control of the Magma Design System, designed to live as a direct child of `<mds-pref>` |
88
+ | `mds-pref-theme-variant` | The `<mds-pref-theme-variant>` web component is the theme-switcher segment of the Magma accessibility preferences panel, designed to live as a direct child of `<mds-pref>` |
89
+ | `mds-pref-theme-variant-item` | The `<mds-pref-theme-variant-item>` web component is a single selectable theme entry inside the `<mds-pref-theme-variant>` preference picker |
90
+ | `mds-price-table` | The `<mds-price-table>` web component is the layout container of the Magma Design System pricing-table family |
91
+ | `mds-price-table-features` | The `<mds-price-table-features>` web component is the feature-matrix block of the Magma Design System pricing-table family |
92
+ | `mds-price-table-features-cell` | The `<mds-price-table-features-cell>` web component is a single cell within a feature comparison row of the Magma price table, rendering one of several visual representations (a support icon, plain text, a label, or arbitrary custom content) depending on its `type` |
93
+ | `mds-price-table-features-row` | The `<mds-price-table-features-row>` web component is a layout child of `<mds-price-table-features>` that represents a single horizontal row inside the feature-comparison table, conceptually playing the role of a table row (`<tr>`). |
94
+ | `mds-price-table-header` | The `<mds-price-table-header>` web component is the layout child that forms the top band of a `<mds-price-table>`, aligning an optional leading title cell with the per-plan `<mds-price-table-list>` columns so the header sits in the same column grid as the feature rows below it |
95
+ | `mds-price-table-list` | The `<mds-price-table-list>` web component is a single pricing-plan column inside the `<mds-price-table>` layout container |
96
+ | `mds-price-table-list-item` | The `<mds-price-table-list-item>` web component represents a single feature row inside a `<mds-price-table-list>`, pairing a supported/unsupported status icon with a textual feature label |
97
+ | `mds-progress` | The `<mds-progress>` web component is the progress indicator of the Magma Design System, rendering the completion state of a determinate task as a bar or ring |
98
+ | `mds-push-notification` | The `<mds-push-notification>` web component is the Magma Design System container that hosts and orchestrates a stack of transient notification items, managing their show/hide lifecycle, entry/exit animations, and overall visibility |
99
+ | `mds-push-notification-item` | The `<mds-push-notification-item>` web component is a single notification card rendered inside its parent container `<mds-push-notification>` |
100
+ | `mds-quote` | The `<mds-quote>` web component is the Magma Design System primitive for rendering a stylized blockquote: it wraps quoted text in decorative typographic quotation marks (` ... `) and exposes an optional attribution slot, replacing a hand-styled `<blockquote>` + citation markup. |
101
+ | `mds-radial-menu` | The `<mds-radial-menu>` web component is a floating action menu of the Magma Design System that arranges its child items along a circular arc around a central trigger button, expanding them outward when opened |
102
+ | `mds-radial-menu-item` | The `<mds-radial-menu-item>` web component is a single actionable spoke of the `<mds-radial-menu>` compound |
103
+ | `mds-radial-progress` | The `<mds-radial-progress>` web component renders a circular progress indicator that visualizes a completion ratio as a ring with a numeric percentage at its center |
104
+ | `mds-separator` | The `<mds-separator>` web component is the visual divider of the Magma Design System: a thin, full-radius horizontal rule used to partition content into distinct groups |
105
+ | `mds-spinner` | The `<mds-spinner>` web component is the Magma Design System's loading/await indicator: a self-contained, animated SVG spinner used standalone or embedded inside host components (`mds-button`, `mds-input`, `mds-entity`) to signal an in-progress, indeterminate operation |
106
+ | `mds-status-bar` | The `<mds-status-bar>` web component is a persistent action bar of the Magma Design System that docks a small set of actions (typically `mds-button` elements) to an edge of the viewport, accompanied by an optional descriptive label |
107
+ | `mds-stepper-bar` | The `<mds-stepper-bar>` web component is the Magma Design System container that orchestrates a multi-step progress flow, coordinating a set of slotted `<mds-stepper-bar-item>` children and revealing the matching content panel for the active step |
108
+ | `mds-stepper-bar-item` | The `<mds-stepper-bar-item>` web component represents a single step inside a `<mds-stepper-bar>` progress indicator, rendering the step's icon, optional ordinal label, descriptive text and status badge |
109
+ | `mds-tab` | The `<mds-tab>` web component is the compound container that orchestrates a tabbed navigation in the Magma Design System |
110
+ | `mds-tab-bar` | The `<mds-tab-bar>` web component is the compound container of the Magma Design System that groups a set of `<mds-tab-bar-item>` children into a single selectable navigation bar, owning the mutual-exclusion logic that keeps exactly one item active at a time. |
111
+ | `mds-tab-bar-item` | The `<mds-tab-bar-item>` web component is a single selectable tab within the `<mds-tab-bar>` container |
112
+ | `mds-tab-item` | The `<mds-tab-item>` web component is the individual, clickable tab control of the Magma Design System, designed to be slotted into the default slot of its parent `<mds-tab>` |
113
+ | `mds-table` | The `<mds-table>` web component is the root container of the Magma Design System tabular data system |
114
+ | `mds-table-body` | The `<mds-table-body>` web component is the row-group container of the Magma Design System tabular data system, used inside `<mds-table>` |
115
+ | `mds-table-cell` | The `<mds-table-cell>` web component is the data-cell building block of the Magma table, designed to be slotted inside `<mds-table-row>` |
116
+ | `mds-table-footer` | The `<mds-table-footer>` web component is a structural child of `<mds-table>` that groups the footer rows of a table - typically used for totals, summaries, or pagination rows |
117
+ | `mds-table-header` | The `<mds-table-header>` web component is the header region of a Magma table, used exclusively as a direct slot child of its parent `<mds-table>` |
118
+ | `mds-table-header-cell` | The `<mds-table-header-cell>` web component is the column-header cell of a Magma data table |
119
+ | `mds-table-row` | The `<mds-table-row>` web component represents a single data row inside a `<mds-table>` (slotted through `mds-table-body`, `mds-table-header`, or `mds-table-footer`) |
120
+ | `mds-text` | The `<mds-text>` web component is the foundational typography primitive of the Magma Design System |
121
+ | `mds-toast` | 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 |
122
+ | `mds-tooltip` | The `<mds-tooltip>` web component is the floating contextual hint of the Magma Design System |
123
+ | `mds-tree` | 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 |
124
+ | `mds-tree-item` | 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 |
125
+ | `mds-url-view` | The `<mds-url-view>` web component renders an embedded preview of an external web page inside a framed browser-like window, wrapping a native `<iframe>` with a titled header, an identifying icon, and a dismiss control |
126
+ | `mds-usage` | The `<mds-usage>` web component is a documentation-oriented annotation block of the Magma Design System used to frame example content as a recommendation, a warning, or an informational note |
127
+ | `mds-video-wall` | The `<mds-video-wall>` web component is the Magma Design System's full-bleed background video surface, used to render an autoplaying, looping ambient video behind foreground content |
128
+ | `mds-zero` | The `<mds-zero>` web component is the empty-state (zero-data) panel of the Magma Design System: a centered, vertically stacked layout that pairs an illustration, explanatory copy, and a call-to-action to guide users when a list, search, or section has no content to show |
package/agents/install.md ADDED
@@ -0,0 +1,132 @@
1
+ <!--
2
+ GENERATED FILE - do not edit by hand.
3
+ Source of truth: docs/agents/ in the magma monorepo.
4
+ Regenerate with: npm run sync.agent-docs (from the stencil package).
5
+ -->
6
+ # install angular.md
7
+
8
+ ## Purpose
9
+
10
+ Install Magma in an Angular app (>= 18.2) via the Angular wrapper
11
+ `@maggioli-design-system/magma-angular`, which exposes the `mds-*` components as
12
+ Angular directives through `MagmaModule`.
13
+
14
+ First do the shared asset setup in [`assets.md`](assets.md) (styles, fonts, icons).
15
+ This file only covers package install and Angular-specific registration.
16
+
17
+ ## 1. Install
18
+
19
+ ```bash
20
+ npm i @maggioli-design-system/magma-angular @maggioli-design-system/magma
21
+ ```
22
+
23
+ Peer dependencies: `@angular/common` and `@angular/core` `^18.2.0`. `magma-angular`
24
+ follows the same major version as `magma` (see [`AGENTS.md`](../AGENTS.md) matrix). Then
25
+ install the assets from [`assets.md`](assets.md):
26
+
27
+ ```bash
28
+ npm i @maggioli-design-system/styles @maggioli-design-system/design-tokens @maggioli-design-system/svg-icons
29
+ npm i @fontsource/karla @fontsource/merriweather @fontsource/roboto @fontsource/roboto-mono
30
+ ```
31
+
32
+ ## 2. Register the components
33
+
34
+ ### NgModule app
35
+
36
+ ```typescript
37
+ import { MagmaModule } from '@maggioli-design-system/magma-angular';
38
+
39
+ @NgModule({
40
+ imports: [
41
+ // ...,
42
+ MagmaModule.forRoot(),
43
+ ],
44
+ bootstrap: [AppComponent],
45
+ })
46
+ export class AppModule {}
47
+ ```
48
+
49
+ ### Standalone app
50
+
51
+ Import `MagmaModule` in the standalone component:
52
+
53
+ ```typescript
54
+ import { MagmaModule } from '@maggioli-design-system/magma-angular';
55
+
56
+ @Component({
57
+ selector: 'app-root',
58
+ standalone: true,
59
+ templateUrl: './app.component.html',
60
+ styleUrl: './app.component.scss',
61
+ imports: [/* ..., */ MagmaModule],
62
+ })
63
+ export class AppComponent implements OnInit {}
64
+ ```
65
+
66
+ And provide the module config in `app.config.ts`:
67
+
68
+ ```typescript
69
+ import { importProvidersFrom, ApplicationConfig } from '@angular/core';
70
+ import { MagmaModule } from '@maggioli-design-system/magma-angular';
71
+
72
+ export const appConfig: ApplicationConfig = {
73
+ providers: [
74
+ // ...,
75
+ importProvidersFrom(MagmaModule.forRoot()),
76
+ ],
77
+ };
78
+ ```
79
+
80
+ Use the components in templates like native elements:
81
+
82
+ ```html
83
+ <mds-button variant="primary" tone="strong">Save</mds-button>
84
+ <mds-icon name="action-email-send"></mds-icon>
85
+ ```
86
+
87
+ ## 3. Set the icon path
88
+
89
+ Set `mdsIconSvgPath` once at app startup, before the first `mds-icon` renders - e.g.
90
+ in the root component constructor or an `APP_INITIALIZER`:
91
+
92
+ ```typescript
93
+ sessionStorage.setItem('mdsIconSvgPath', '/svg/');
94
+ ```
95
+
96
+ For Angular Universal (SSR), guard against the server where `sessionStorage` is
97
+ undefined - set it inside a browser-platform check (`isPlatformBrowser`) or in a
98
+ client-only initializer.
99
+
100
+ ## 4. Serve the icon SVGs and styles
101
+
102
+ - Copy `@maggioli-design-system/svg-icons/dist/svg/` to the served `/svg/` path. With
103
+ the Angular CLI, add an `assets` glob in `angular.json`:
104
+
105
+ ```json
106
+ "assets": [
107
+ {
108
+ "glob": "**/*.svg",
109
+ "input": "node_modules/@maggioli-design-system/svg-icons/dist/svg",
110
+ "output": "/svg"
111
+ }
112
+ ]
113
+ ```
114
+
115
+ - Import the global CSS block from [`assets.md`](assets.md) in `styles.css` /
116
+ `styles.scss` so the cascade-layer order is preserved.
117
+
118
+ ## Gotchas
119
+
120
+ - Use the `MagmaModule` directives rather than raw custom elements. If you ever use
121
+ `mds-*` tags without the wrapper, add `CUSTOM_ELEMENTS_SCHEMA` to the
122
+ module/component so Angular does not error on unknown elements - but the wrapper is
123
+ the supported path.
124
+ - Keep `magma` and `magma-angular` on the exact same version; the wrapper is
125
+ generated against a specific `magma` build.
126
+ - Custom events (`mdsButtonClick`, ...) bind via the wrapper's Angular outputs - see
127
+ the Magma component conventions guide for event names.
128
+
129
+ ## See also
130
+
131
+ - [`assets.md`](assets.md) - styles / fonts / icons / identity (canonical)
132
+ - the Magma component conventions guide - component conventions, events, slots