@maggioli-design-system/magma-react 2.0.0 → 2.1.0

package/agents/theming.md

@@ -0,0 +1,140 @@
+<!--
+  GENERATED FILE - do not edit by hand.
+  Source of truth: docs/agents/ in the magma monorepo.
+  Regenerate with: npm run sync.agent-docs (from the stencil package).
+-->
+# Magma styles - theming, dark mode and preferences
+
+> Scope: dark mode, the user preferences (contrast, motion, consumption), the named
+> themes, the surface levels and elevation, the global design decisions you may override,
+> and the corner geometry axis. Requires the styles setup in [`assets.md`](assets.md).
+> The color roles themselves: [`color.md`](color.md).
+
+The component layer already handles these - **do not re-implement them in app code**.
+
+## Dark mode and preferences
+
+Handled at the palette level - no per-element classes. Components read tokens, not
+literal colours, so they invert automatically. Activate on `<html>`:
+
+```html
+<html class="pref-mode-system"><!-- or pref-mode-light / pref-mode-dark --></html>
+```
+
+Same pattern for `pref-contrast-*`, `pref-animation-*` and `pref-consumption-*` (high
+contrast, reduced motion, low consumption): the classes on `<html>` cascade through. To
+let the user choose, each preference has its component - `mds-pref-mode`,
+`mds-pref-contrast`, `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-theme`,
+`mds-pref-language` - and `mds-pref` groups them in one panel; they write the classes and
+remember the choice. Never write `color-scheme` or dark-mode media queries by hand.
+
+## Named themes
+
+A named theme retints the whole neutral scaffolding of the page at once - surfaces,
+wash, borders, text, the inverse chip - and keeps it contrast-checked. It is one
+attribute on `<html>`, and it needs `themes.css` ([`assets.md`](assets.md)):
+
+```html
+<html data-theme-name="cool"><!-- or "warm"; no attribute = the default theme --></html>
+```
+
+| Theme | Family | Cast |
+| --- | --- | --- |
+| (none) | `neutral` | grey |
+| `cool` | `porcelain` | blue-grey |
+| `warm` | `bisque` | warm grey |
+
+The status colors (info, success, warning, danger) never change with the theme. To let
+the user choose, use `mds-pref-theme`: it writes the attribute, remembers the choice and
+also carries the corner shape (below). A theme works only on code that paints with the
+semantic roles; a raw palette step stays as it is. Defining your own theme is not a
+consumer feature yet.
+
+## Surfaces and elevation
+
+Every neutral background is one of five surface levels. They are not five greys to pick
+from: each one says where the element sits relative to the page.
+
+```text
+surface-default          the page, the canvas everything else sits on
+  surface-sunken         recessed into the page: wells, insets, code blocks, tracks
+  surface-muted          on the page plane, grouped: zebra rows, a subtle section
+  surface-raised         lifted off the page: cards, panels, sticky headers
+    surface-overlay      floating above everything: modal, dropdown, popover, tooltip
+```
+
+The ladder in the default theme (`--magma-surface-*`, Tailwind `bg-surface-*`):
+
+| Level | Light | Dark |
+| --- | --- | --- |
+| `sunken` | `#e8e8e8` | `#020202` |
+| `muted` | `#ebebeb` | `#0d0d0d` |
+| `default` | `#f2f2f2` | `#1d1d1d` |
+| `raised` | `#f8f8f8` | `#303030` |
+| `overlay` | `#ffffff` | `#4a4a4a` |
+
+In both modes the ladder rises toward the light: `sunken` and `muted` sit below the page,
+`raised` and `overlay` above it. Light keeps the page a soft grey so that a card can be
+lighter than it; dark lifts the page off pure black so that there is room below it.
+
+**In light, elevation needs a shadow.** The steps above the page are close in light
+(`#f2f2f2` page, `#f8f8f8` card), so the fill alone barely separates a raised element; in
+dark the fill does most of the work. Pair `raised` and `overlay` with a shadow, as the
+components do (`mds-card` uses `--shadow-md-sharp`, `mds-modal` `--shadow-2xl`):
+
+```css
+.panel {
+  background: rgb(var(--magma-surface-raised));
+  box-shadow: var(--shadow-md-sharp);
+}
+```
+
+```html
+<div class="bg-surface-raised shadow-md-sharp">...</div>
+```
+
+An overlay separates from what is under it by its shadow, not by a border: in dark
+`border-muted` is darker than `surface-overlay`.
+
+**Text is safe on every level.** Each text role is computed against the least
+contrasting surface of its family, so `text-default`, `text-muted` and the rest are
+legible on all five levels in both modes (checked in CI). The tinted pills are a
+different device with tighter rules: see the wash levels in [`color.md`](color.md).
+
+**Themes and contrast move the levels, not your code.** Under a named theme the five
+levels take the theme's cast. Under `pref-contrast-more` the page (`surface-default`)
+becomes the paper of the mode (`#fff` light, `#000` dark) while `raised` and `overlay`
+keep their step, so cards and floating layers still stand off the page. Code that paints
+with the roles follows both with no rule of its own.
+
+**Roles, not primitives.** `--surface-neutral-raised` and its siblings
+(`--surface-<family>-*`) are the design-tokens primitives behind the roles, one set per
+family: they follow the mode but not the named theme nor the contrast preference. Paint
+with `--magma-surface-*`.
+
+## Global design decisions
+
+Override `--magma-*` vars only inside the `overrides` cascade layer:
+`--magma-disabled-opacity` (`0.5`), `--magma-backdrop-opacity` (`0.1`),
+`--magma-outline-focus`.
+
+```css
+@layer overrides { :root { --magma-disabled-opacity: 0.35; } }
+```
+
+## Corner geometry
+
+Corner geometry is an axis of its own, because the shape and the radius scale tuned
+for it have to move together: a squircle cuts a much smaller corner than a round one
+at the same radius. Set `data-corner-shape` - on `<html>`, or on any element to
+deviate for that subtree only - and both follow. Overriding `--magma-corner-shape`
+by itself changes the shape WITHOUT the scale.
+
+```html
+<html data-corner-shape="round">
+<section data-corner-shape="squircle">...</section>
+```
+
+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.

package/agents/typography.md

@@ -0,0 +1,32 @@
+<!--
+  GENERATED FILE - do not edit by hand.
+  Source of truth: docs/agents/ in the magma monorepo.
+  Regenerate with: npm run sync.agent-docs (from the stencil package).
+-->
+# Magma styles - typography
+
+> Scope: setting text in your own UI with Magma's typography utilities. Requires the
+> styles and fonts setup in [`assets.md`](assets.md).
+
+## Typography utilities
+
+Use the semantic `text-*` utilities instead of composing `font-*` + `text-*`:
+`text-title-h1`..`h6`, `text-title-action`, `text-info-{paragraph,detail,caption,label,option,tip}`,
+`text-read-{paragraph,detail,caption}`, `text-code-{snippet,hack}`.
+
+They come from `styles/dist/tailwind/typography.css` (see the Tailwind section of
+[`assets.md`](assets.md)). Without Tailwind, the same scale is a plain CSS class per style,
+named `typography-*` (`typography-title-h1`, `typography-info-detail`, ...), in
+`@maggioli-design-system/styles/dist/css/utility-typography.css`: import it in the
+`utilities` layer.
+
+Inside component markup, `mds-text` sets a style through its `typography` prop (`h1` ..
+`h6`, `action`, `paragraph`, `detail`, `caption`, `label`, `option`, `tip`, `snippet`,
+`hack`); `variant="read"` switches `paragraph`, `detail` and `caption` from the `info`
+family to the `read` one.
+
+```html
+<h2 class="text-title-h3">Invoices</h2>
+<p class="typography-read-paragraph">Plain CSS, no Tailwind.</p>
+<mds-text typography="h3">Invoices</mds-text>
+```

package/agents/variants.md

@@ -0,0 +1,112 @@
+<!--
+  GENERATED FILE - do not edit by hand.
+  Source of truth: docs/agents/ in the magma monorepo.
+  Regenerate with: npm run sync.agent-docs (from the stencil package).
+-->
+# Magma components - variant and tone
+
+> Scope: the two independent axes many components accept - `variant` (the color role)
+> and `tone` (the visual intensity) - their values, and how to check what one component
+> accepts. The other component rules: [`conventions.md`](conventions.md). The color
+> roles behind each variant: [`color.md`](color.md).
+
+Many components accept both `variant` and `tone` props. These are independent axes:
+
+- `variant` controls the **color role** - it answers _what kind of action/state this
+  is_.
+- `tone` controls the **visual intensity** - it answers _how much emphasis this should
+  have_, independent of `variant`.
+
+```html
+<mds-button variant="primary" tone="strong">Save</mds-button>
+<mds-button variant="error" tone="outline">Delete</mds-button>
+```
+
+The same `variant` + different `tone` is the right way to express importance - do not
+invent custom CSS to dim or saturate. Pick the variant that matches the **meaning**, not
+the colour you happen to want.
+
+> Magma 2.0 breaking rename of `tone`: `ghost` -> `outline`; `quiet` -> `text` on
+> `mds-button`, `mds-radial-menu` and `mds-radial-menu-item` (the only components with a
+> `text` tone), `quiet` -> `weak` everywhere else. The codemod
+> (`@maggioli-design-system/magma-codemods`) applies both.
+
+## Variants
+
+Allowed values depend on the component but draw from these families:
+
+| Family   | Values                                | Use for                                     | Paints with ([`color.md`](color.md))    |
+| -------- | ------------------------------------- | ------------------------------------------- | ---------------------------------------- |
+| Accent   | `primary`, `secondary`, `ai`          | Actions and selection, AI-driven features   | `--magma-accent-*`, `--magma-accent-ai-*` |
+| Status   | `info`, `success`, `warning`, `error` | Communicating state                         | `--magma-<hue>-*` (`error` is the `danger` hue) |
+| Neutral  | `dark`, `light`                       | Neutral chrome buttons, chips, badges       | the neutral roles                        |
+| Label    | `amaranth`, `red`, `aqua`, `blue`, ... | Categories, tags, visual grouping          | the `label-*` palette                    |
+| Identity | `google`, `apple`                     | Sign-in buttons (`mds-button`, `mds-radial-menu`, `mds-radial-menu-item`) | fixed by the provider's guidelines; `tone` is ignored |
+
+| Variant name | Family   | Description                                                                 |
+| ------------ | -------- | --------------------------------------------------------------------------- |
+| `primary`    | Accent   | The most important actions or messages                                      |
+| `secondary`  | Accent   | Kept for compatibility: it renders exactly like `primary`. A second brand colour is a named theme, not a variant ([`theming.md`](theming.md)); for a supporting action lower the `tone` instead |
+| `ai`         | Accent   | AI-generated content or AI-powered features                                 |
+| `error`      | Status   | Failures, destructive actions, validation issues                            |
+| `success`    | Status   | Successful operations, positive confirmation                                |
+| `warning`    | Status   | Caution, non-blocking issues that require attention                         |
+| `info`       | Status   | Neutral informational content or guidance                                   |
+| `dark`       | Neutral  | Neutral chrome. Painted with roles that follow the mode, so it is not "for light backgrounds": check the component's `pattern.md` for how it renders |
+| `light`      | Neutral  | The other half of the neutral pair, same caveat as `dark`                   |
+| `amaranth`   | Label    | Decorative amaranth label for tags, categories, or visual grouping          |
+| `red`        | Label    | Decorative red label for tags, categories, or visual grouping               |
+| `aqua`       | Label    | Decorative aqua label for tags, categories, or visual grouping              |
+| `blue`       | Label    | Decorative blue label for tags, categories, or visual grouping              |
+| `green`      | Label    | Decorative green label for tags, categories, or visual grouping             |
+| `lime`       | Label    | Decorative lime label for tags, categories, or visual grouping              |
+| `orange`     | Label    | Decorative orange label for tags, categories, or visual grouping            |
+| `orchid`     | Label    | Decorative orchid label for tags, categories, or visual grouping            |
+| `purple`     | Label    | Decorative purple label for tags, categories, or visual grouping            |
+| `sky`        | Label    | Decorative sky label for tags, categories, or visual grouping               |
+| `violet`     | Label    | Decorative violet label for tags, categories, or visual grouping            |
+| `yellow`     | Label    | Decorative yellow label for tags, categories, or visual grouping            |
+
+A label colour never communicates state: for state use a status variant.
+
+## Tones
+
+The tone vocabulary, from the most to the least emphasis:
+
+| Tone      | Weight              | Visual                                                     |
+| --------- | ------------------- | ---------------------------------------------------------- |
+| `strong`  | Highest emphasis    | Solid filled background                                    |
+| `weak`    | Medium emphasis     | Subtle tinted background, for supporting context           |
+| `outline` | Medium-low emphasis | Border only, no fill                                       |
+| `text`    | Lowest emphasis     | No border, no background - just the label, in-text actions |
+| `box`     | Boxed container     | High-contrast container style                              |
+
+Only `strong` and `weak` are common. `outline` exists on `mds-button`, `mds-badge`,
+`mds-radial-menu` and `mds-radial-menu-item`; `text` on `mds-button`, `mds-radial-menu`
+and `mds-radial-menu-item`; `box` on `mds-button` and `mds-banner`.
+
+## What one component accepts
+
+The values a specific component accepts for `tone`, `variant`, `size`, etc. are
+**narrower** than the vocabularies above. For example, `mds-button` accepts
+`tone="outline"` but `mds-banner` does not.
+
+To verify a prop value before using it, read the Props table in the component's
+`AGENTS.md` (listed in [`components.md`](components.md)): the Type column lists the
+allowed values. The typed signatures are also in
+`@maggioli-design-system/magma/dist/types/components.d.ts`, where a prop is typed by
+name (e.g. `tone?: ToneMinimalBoxVariantType`).
+
+The `tone` types:
+
+| Type                        | Allowed `tone` values                      | Components |
+| --------------------------- | ------------------------------------------ | ---------- |
+| `ToneMinimalVariantType`    | `strong`, `weak`                           | `mds-avatar`, `mds-avatar-stack-item`, `mds-button-dropdown`, `mds-chip`, `mds-entity`, `mds-label`, `mds-push-notification-item`, `mds-toast` |
+| `ToneMinimalBoxVariantType` | `strong`, `weak`, `box`                    | `mds-banner` |
+| `ToneSmartVariantType`      | `strong`, `weak`, `outline`                | `mds-badge` |
+| `ToneVariantType`           | `outline`, `strong`, `text`, `weak`        | `mds-radial-menu`, `mds-radial-menu-item` |
+| `ToneBoxVariantType`        | `outline`, `strong`, `text`, `weak`, `box` | `mds-button` |
+| `ToneSimpleVariantType`     | `strong`, `weak`, `text`                   | none today |
+
+`variant`, `size`, and other constrained props follow the same pattern (e.g.
+`ThemeVariantType`, `ThemeFullVariantType`, `ChipVariantType`, `ProgressBarSizeType`).

package/dist/mds-button-dropdown.js

@@ -7,6 +7,6 @@ export const MdsButtonDropdown = /*@__PURE__*/ createComponent({
     elementClass: MdsButtonDropdownElement,
     // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
     react: React,
-    events: {},
+    events: { onMdsButtonDropdownClick: 'mdsButtonDropdownClick' },
     defineCustomElement: defineMdsButtonDropdown
 });

package/dist/mds-button-dropdown.server.js

@@ -10,6 +10,8 @@ export const MdsButtonDropdown = /*@__PURE__*/ createComponent({
         autoFocus: 'auto-focus',
         icon: 'icon',
         type: 'type',
+        name: 'name',
+        value: 'value',
         variant: 'variant',
         tone: 'tone',
         size: 'size',

package/dist/mds-button.server.js

@@ -12,6 +12,8 @@ export const MdsButton = /*@__PURE__*/ createComponent({
         icon: 'icon',
         iconPosition: 'icon-position',
         type: 'type',
+        name: 'name',
+        value: 'value',
         variant: 'variant',
         tone: 'tone',
         size: 'size',

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

@@ -14,7 +14,8 @@ export const MdsInputDateRange = /*@__PURE__*/ createComponent({
         delay: 'delay',
         hideToday: 'hide-today',
         dualCalendar: 'dual-calendar',
-        name: 'name'
+        name: 'name',
+        disabled: 'disabled'
     },
     hydrateModule: typeof window === 'undefined' ? import('@maggioli-design-system/magma/hydrate') : undefined,
     clientModule: clientComponents.MdsInputDateRange,

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

@@ -9,6 +9,7 @@ export const MdsInputOtp = /*@__PURE__*/ createComponent({
         accessibleName: 'aria-label',
         length: 'length',
         autosubmit: 'autosubmit',
+        disabled: 'disabled',
         value: 'value'
     },
     hydrateModule: typeof window === 'undefined' ? import('@maggioli-design-system/magma/hydrate') : undefined,

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

@@ -7,6 +7,8 @@ export const MdsInputUpload = /*@__PURE__*/ createComponent({
     tagName: 'mds-input-upload',
     properties: {
         accept: 'accept',
+        disabled: 'disabled',
+        name: 'name',
         maxFileSize: 'max-file-size',
         maxFiles: 'max-files',
         sort: 'sort'

package/dist/types/mds-button-dropdown.d.ts

@@ -2,8 +2,11 @@
  * This file was automatically generated by the Stencil React Output Target.
  * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
  */
-import type { StencilReactComponent } from '@stencil/react-output-target/runtime';
+import type { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
+import { type MdsButtonDropdownCustomEvent } from "@maggioli-design-system/magma";
 import type { Components } from "@maggioli-design-system/magma/dist/components";
 import { MdsButtonDropdown as MdsButtonDropdownElement } from "@maggioli-design-system/magma/dist/components/mds-button-dropdown.js";
-export type MdsButtonDropdownEvents = NonNullable<unknown>;
+export type MdsButtonDropdownEvents = {
+    onMdsButtonDropdownClick: EventName<MdsButtonDropdownCustomEvent<void>>;
+};
 export declare const MdsButtonDropdown: StencilReactComponent<MdsButtonDropdownElement, MdsButtonDropdownEvents, Components.MdsButtonDropdown>;

package/dist/types/mds-button-dropdown.server.d.ts

@@ -2,10 +2,13 @@
  * This file was automatically generated by the Stencil React Output Target.
  * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
  */
-import type { StencilReactComponent } from '@stencil/react-output-target/runtime';
+import type { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
 import { type SerializeShadowRootOptions } from '@stencil/react-output-target/ssr';
+import { type MdsButtonDropdownCustomEvent } from "@maggioli-design-system/magma";
 import type { Components } from "@maggioli-design-system/magma/dist/components";
 import { MdsButtonDropdown as MdsButtonDropdownElement } from "@maggioli-design-system/magma/dist/components/mds-button-dropdown.js";
 export declare const serializeShadowRoot: SerializeShadowRootOptions;
-export type MdsButtonDropdownEvents = NonNullable<unknown>;
+export type MdsButtonDropdownEvents = {
+    onMdsButtonDropdownClick: EventName<MdsButtonDropdownCustomEvent<void>>;
+};
 export declare const MdsButtonDropdown: StencilReactComponent<MdsButtonDropdownElement, MdsButtonDropdownEvents, Components.MdsButtonDropdown>;

package/dist/types/mds-input-select.d.ts

@@ -3,10 +3,10 @@
  * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
  */
 import type { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
-import { type MdsInputEventDetail, type MdsInputSelectCustomEvent } from "@maggioli-design-system/magma";
+import { type MdsInputSelectCustomEvent, type MdsInputSelectEventDetail } from "@maggioli-design-system/magma";
 import type { Components } from "@maggioli-design-system/magma/dist/components";
 import { MdsInputSelect as MdsInputSelectElement } from "@maggioli-design-system/magma/dist/components/mds-input-select.js";
 export type MdsInputSelectEvents = {
-    onMdsInputSelectChange: EventName<MdsInputSelectCustomEvent<MdsInputEventDetail>>;
+    onMdsInputSelectChange: EventName<MdsInputSelectCustomEvent<MdsInputSelectEventDetail>>;
 };
 export declare const MdsInputSelect: StencilReactComponent<MdsInputSelectElement, MdsInputSelectEvents, Components.MdsInputSelect>;

package/dist/types/mds-input-select.server.d.ts

@@ -4,11 +4,11 @@
  */
 import type { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
 import { type SerializeShadowRootOptions } from '@stencil/react-output-target/ssr';
-import { type MdsInputEventDetail, type MdsInputSelectCustomEvent } from "@maggioli-design-system/magma";
+import { type MdsInputSelectCustomEvent, type MdsInputSelectEventDetail } from "@maggioli-design-system/magma";
 import type { Components } from "@maggioli-design-system/magma/dist/components";
 import { MdsInputSelect as MdsInputSelectElement } from "@maggioli-design-system/magma/dist/components/mds-input-select.js";
 export declare const serializeShadowRoot: SerializeShadowRootOptions;
 export type MdsInputSelectEvents = {
-    onMdsInputSelectChange: EventName<MdsInputSelectCustomEvent<MdsInputEventDetail>>;
+    onMdsInputSelectChange: EventName<MdsInputSelectCustomEvent<MdsInputSelectEventDetail>>;
 };
 export declare const MdsInputSelect: StencilReactComponent<MdsInputSelectElement, MdsInputSelectEvents, Components.MdsInputSelect>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maggioli-design-system/magma-react",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "main": "dist/components.js",
   "module": "dist/components.js",
   "types": "dist/types/components.d.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@maggioli-design-system/magma": "2.0.0",
+    "@maggioli-design-system/magma": "2.1.0",
     "@stencil/react-output-target": "1.6.2"
   },
   "repository": {