@nxgt/material-vue 0.26.1 → 0.28.0

package/docs/guides/theming.md

@@ -32,8 +32,9 @@ build:
   (`RichTextEditor` code blocks), vue-sonner (`Toaster`),
   vue-advanced-cropper (`ImageCropper`), the `Spinner` animation, and the
   `nxgt-*` classes of `ButtonGroup`, `ContactItem`, `OpeningHoursItem`,
-  `AttributeForm` and `AttributeValuesForm` (the packages are dependencies,
-  the rest ship in `lib/components/`);
+  `AttributeForm` and `AttributeValuesForm`, and the required-field mark drawn
+  after a `Label` (the packages are dependencies, the rest ship in
+  `lib/components/`);
 - `@source "../dist"`, so your build scans the compiled components;
 - the **tokens**: CSS variables on `:root`, and their dark values on `.dark`
   and `[data-theme="dark"]`;
@@ -51,9 +52,11 @@ build:
 | `--primary`, `--primary-foreground` | `bg-primary`, `text-primary-foreground` | filled buttons, active states, focus |
 | `--secondary`, `--secondary-foreground` | `bg-secondary`, … | the secondary colour |
 | `--muted`, `--muted-foreground` | `bg-muted`, `text-muted-foreground` | quiet surfaces, hints, placeholders |
+| `--track`, `--track-fill` | `bg-track`, `bg-track-fill`, `border-track-fill` | the empty part of a slider or meter, the drawer handle; the slider range and thumb |
 | `--accent`, `--accent-foreground` | `bg-accent`, … | hover surfaces |
-| `--error`, `--success`, `--info`, `--warning` (+ `-foreground`) | `bg-error`, `text-success`, … | the status colours of `Button`, `Alert`, `Badge`, toasts; `--error` also colours `variant="error"` menu items |
-| `--destructive` | `bg-destructive`, `text-destructive` | destructive actions (menu items use `--error`) |
+| `--error`, `--success`, `--info`, `--warning` (+ `-foreground`) | `bg-error`, `text-success`, … | the status colours of `Button`, `Alert`, `Badge`, toasts |
+| `--error-text` | `text-error-text` | error drawn as text: field messages, `HelperText` in its error state, form and dialog errors, `variant="error"` menu items |
+| `--destructive` | `bg-destructive`, `text-destructive` | deprecated alias of `--error`: the light theme sets it to `var(--error)`, the dark theme keeps its own value; use `--error` |
 | `--card`, `--popover`, `--tooltip` (+ `-foreground`) | `bg-card`, `bg-popover`, `bg-tooltip` | surfaces |
 | `--border`, `--input`, `--ring` | `border-border`, `border-input`, `ring-ring` | outlines |
 | `--chart-1` … `--chart-5` | `bg-chart-1`, … | chart series (the charts read them at runtime) |
@@ -90,7 +93,9 @@ Redefine the variables **after** the import, for light and dark separately:
 Override the variable, not the `@theme` entry: `--color-primary` is defined as
 `var(--primary)`, so one change reaches both modes and every derived colour.
 
-For a single area of the page, set the variables on a wrapper:
+For a single area of the page, set the `--color-*` variables on a wrapper
+(the `@theme` entries are resolved on the root, so setting `--primary` on an
+element below it changes nothing):
 
 ```vue
 <script setup lang="ts">
@@ -98,12 +103,149 @@ import { Button } from '@nxgt/material-vue/components';
 </script>
 
 <template>
-  <section :style="{ '--primary': 'var(--error)' }">
+  <section :style="{ '--color-primary': 'var(--error)' }">
     <Button>Delete workspace</Button>
   </section>
 </template>
 ```
 
+## Contrast and reduced motion
+
+**Contrast.** The shipped light palette keeps the text of every filled status
+colour at 4.5:1 or more (WCAG 1.4.3): `--secondary` 5.7:1, `--success` 5.6:1,
+`--info` 5.8:1 and `--warning` 5.3:1 against their `-foreground`, and
+`--secondary` as text (a `tonal`, `outlined` or `link` `Button`) 6.0:1 on
+`--background`, 4.8:1 on its own 15 % `tonal` tint.
+
+The dark theme keeps brighter values, read as text on the dark surfaces: the
+dark `--secondary` (`oklch(0.66 0.1135 245.65)`) is 6.5:1 on `--background`
+and 5.8:1 on `--card` (a `tonal` secondary `Button` 5.4:1 and 4.6:1). Under
+near-white text those brights are too light, so every filled surface built on
+them is tinted in the dark theme: a filled `secondary` `Button`, `IconButton`
+or `Badge` at 70 % (5.2:1 on `--background`, 4.9:1 on `--card`), a filled
+`success`, `info` or `warning` one at 60 % (7.3:1, 5.7:1 and 7.5:1 on
+`--background`; 6.7:1, 5.3:1 and 7.0:1 on `--card`). Their hover, focus and
+pressed states are tinted further down, so they only gain contrast.
+
+In the light theme the filled `primary`, `secondary`, `success`, `info`,
+`warning` and `error` buttons darken when hovered, focused or pressed (mixed
+with 10, 15 and 20 % black) rather than fading toward the page, so their
+near-white text only gains contrast (the filled `default` variant's states are
+unchanged); a `tonal` button's focus tint is 10 %
+(lighter than its 15 % rest), an `outlined` one's 15 %, and its hover keeps the
+text colour.
+
+The `tonal`, `outlined` and `link` variants of `Button` and `IconButton` draw
+their text and icon in one tone per colour, read on `--background`, on
+`--card` and on the variant's own tint (15 % at most, at rest or focused). In
+the light theme `primary`, `secondary`, `info` and `success` use the token
+itself (5.8, 4.8, 4.9 and 4.7:1 at their lowest) and `warning` and `error` the
+token mixed with 15 % black (6.0 and 5.4:1). In the dark theme `primary` is
+mixed with 60 % white (8.1:1 on `--card`: the token itself is a dark indigo,
+2.2:1), `success` and `warning` with 15 % white (5.0 and 5.4:1), `error` with
+30 % white (5.9:1), and `secondary` and `info` use the token (4.6 and 5.3:1).
+The tones are mixed from the tokens (`color-mix(in oklab, var(--color-error)
+85%, black)`), so an override of a token moves its tone with it; a text colour
+of your own on one of those buttons (`class="text-primary"`) replaces the tone
+and is yours to check.
+
+A `Badge` used as a link (`as-child` around an `<a>`) darkens on hover like a filled
+button (mixed with 10 % black; in the dark theme its tint drops by ten
+points) rather than fading toward the page. A selected `ListTile` draws its
+subtitle in `text-foreground/70` (7.0:1 on the selected tint, where the muted
+colour gave 4.4:1). The light `--error` is `oklch(0.56 0.245 27.325)`, a shade
+darker than the dark theme's: a filled `error` button's near-white text reaches
+4.8:1 (it was 4.6:1). The dark `--error` keeps `0.577`: a lighter value drops
+the filled surface's near-white text below 4.5:1 (`0.62` gives 3.85:1).
+
+**Error text has a token of its own**, `--error-text` (`text-error-text`), so
+the fill can stay dark while the text is light enough to read. The light value
+is `color-mix(in oklab, var(--error) 94%, black)` (5.7:1 on `--background`
+and `--card`, 4.8:1 on the `bg-error/10` tint of a focused menu item, where
+`--error` gives 5.0 and 4.2:1); the dark one is
+`color-mix(in oklab, var(--error) 80%, white)`, 5.9:1 on `--background` and
+5.3:1 on `--card`, where `--error` itself gives 4.2 and 3.8:1. Field messages,
+`HelperText` in its error state, form, dialog and upload errors, a textarea's
+counter over its limit, the error lines of `Terminal`, a
+`variant="error"` menu item and the falling values of the metric cards use it.
+
+Which one to use:
+
+- **`text-error-text`** for an error written as text on a page, card or
+  popover surface (your own validation message, a failed row, an inline
+  error), and for an icon drawn beside that text, so the two match.
+- **`text-error`** (with `bg-error`, `border-error`, `ring-error`,
+  `stroke-error`) for fills, borders, rings and icons that stand alone: those
+  need 3:1 (WCAG 1.4.11), which `--error` reaches in both themes. Text on a
+  filled error surface is `text-error-foreground`.
+
+`--error-text` is computed where it is declared, on the root, and `@theme`
+resolves `--color-error-text` there too: an override of `--error` under `:root`
+and `.dark, [data-theme="dark"]` moves it, but setting `--error-text` or
+`--error` on an element below the root changes nothing. Below the root, set
+`--color-error-text` (and `--color-error` for fills) on that element, or put
+the override on the root.
+
+Storybook's `Guides/Theming/Contrast` measures all of this in both themes:
+the surfaces' text, the error text (`HelperText` and a field's message on
+`--background` and `--card`), the `Alert`s and the `Timeline`, `Button` and
+`IconButton` in every variant and colour, and a `Badge` link in every colour,
+at rest, hovered, focused and pressed, the tracks and the tabs;
+`Data display/ListTile` measures the selected tile. Run them against your own
+tokens after an override.
+
+**Tabs.** An `underline` tab's active label is `--primary` in the light
+theme (7.3:1 on `--background` and `--card`, 6.7:1 on `--muted`) and
+`--primary` mixed with 60 % white in the dark one (10.0:1, 9.0:1 and 7.4:1);
+its bar and every tab's focus outline are `--primary` in the light theme and
+`--track-fill` in the dark one (at least 6.7:1 and 9.0:1 on those surfaces).
+An inactive label is `--muted-foreground`, and turns to `--foreground` when
+hovered. A `segmented` tab's active label is `--foreground` on the raised
+surface (19.9:1 light, 17.0:1 dark); that surface is only 1.1:1 to 1.2:1 on
+the track, so it has a `--muted-foreground` border (5.0:1 light, 4.7:1 dark
+on the track), and the label also changes colour and weight. Storybook's
+`Guides/Theming/Contrast` story `Tabs` measures each label at rest, hovered
+and focused, the outline, the bar and the border, on the three surfaces, in
+both themes.
+
+`--muted-foreground` is 5.5:1 on `--background` and `--card`, 5.1:1 on the
+"paper" tint (`bg-background-paper`, 5 % primary) and 5.0:1 on `--muted` in
+the light theme; in the dark theme it is 6.4:1 on `--background`, 5.7:1 on
+`--card`, 6.3:1 on the paper tint and 4.7:1 on `--muted`. The dark `--muted`
+is a dark surface (`oklch(0.279 0.041 260.031)`, it was the light value, a
+near-white block on a dark page) and `--foreground` on it reaches 14.0:1.
+
+**Tracks.** The empty part of a `Slider`, of the password strength meter and
+the `Drawer` handle use `--track` (`bg-track`), and the `Slider`'s range and
+thumb border `--track-fill` (`bg-track-fill`, `border-track-fill`). In the
+dark theme the track reaches 3.6:1 on `--background` and 3.2:1 on `--card`
+(WCAG 1.4.11; `bg-muted`, a dark surface now, gave 1.4:1 and 1.2:1), and the
+fill 3.4:1 on the track. The light theme keeps a pale track (`--track` is the
+light `--muted`) and `--track-fill` is `--primary`: the thumb, 7.3:1 on the
+page, shows the value. A track, bar, handle or divider of your own drawn with
+`bg-muted` is near invisible in the dark theme now that `--muted` is a dark
+surface: draw it with `bg-track`.
+
+When you override one of these tokens, keep its pair at 4.5:1 (3:1 for an
+icon or a border), or the `Badge`, `Button`, `Alert` and toast text built on it fails
+an accessibility audit. The muted text of a highlighted menu entry (a
+`DropdownMenuShortcut`, the code in `LanguageSwitcher`) switches to
+`--accent-foreground` while the entry is highlighted, so a `--muted-foreground`
+of your own does not have to pass on the highlight colour.
+
+**Reduced motion.** `styles.css` imports `components/reduced-motion.css`: one
+`@media (prefers-reduced-motion: reduce)` rule that turns off the transitions
+and animations of every catalogue component (everything under a `data-slot`,
+and the toasts): dialogs, sheets and menus appear without sliding or fading,
+buttons and toasts without transitions. The `Spinner` and any `animate-spin` element (a spinning
+loading icon) keep turning: they are the only sign that something is loading.
+The rule is `!important` but unlayered and with a specificity of 0, so a
+component's own `duration-*` utility does not outrank it, and your own
+`!important` rule on a class does; to keep one motion for everyone, override it
+on that element with that rule inside `@media (prefers-reduced-motion: reduce)`.
+Your own components outside a `data-slot` are yours: use Tailwind's
+`motion-reduce:` variant on them.
+
 ## Dark mode
 
 Dark values apply under a `.dark` class **or** a `data-theme="dark"`

package/docs/roadmap.md

@@ -19,6 +19,9 @@ Nothing in progress right now; see Next.
 
 ## Later
 
+- **Next major: `ListTile`'s `data-slot` becomes `list-tile`** — it is
+  `item-detail` today, so the name matches the component like every other
+  slot. Breaking for a selector or a test that looks for `item-detail`.
 - **1.0: the same amounts and dates on every machine** — `formatAmount` and
   `formatDate` stop falling back to the runtime's locale when you pass none, so
   a server and a browser always print the same string.
@@ -92,6 +95,31 @@ Nothing in progress right now; see Next.
 
 ## Shipped
 
+- **Tabs in two looks** — `underline`, the new default, whose bar slides to
+  the active tab, and a neutral `segmented` pill; a list that scrolls
+  sideways on a phone instead of widening the page, right-to-left, a visible
+  focus ring, labels that read 4.5:1 in both themes, and an indicator that
+  stops sliding under `prefers-reduced-motion`. `bar` and `line` still work,
+  as deprecated aliases of `underline` and `segmented`. 0.28.0.
+
+- **Accessible by default** — error text in its own `--error-text` colour that
+  reads 4.5:1 in both themes, the empty part of sliders and meters in a
+  `--track` colour that reads 3:1, buttons, badges and status colours that
+  reach WCAG contrast, animations that honour `prefers-reduced-motion`, the
+  page behind a modal layer made `inert`, the first invalid field focused
+  after a failed submit (`focusFirstInvalid`), Escape that reaches the layer
+  below while one closes, and a `Toaster` at the top of a phone whose toasts
+  a tap does not pause and whose actions work over a dialog. 0.27.0.
+- **Fits a phone** — `DataTable` with no height cap by default (`max-height`
+  when it should scroll in a box), a header row at every width, and wide
+  columns that scroll sideways in one region a keyboard can reach; a `Button`
+  never wider than its container (a long label ends in "…", or wraps with
+  `wrap`); `OtpField` slots that shrink to fit a narrow card. 0.27.0.
+- **App shell links, landmarks and scrolling** — menu entries that are real
+  links (middle-click, before hydration, `aria-current="page"`, your router's
+  link through `link-component`), one `<main>` landmark, and a shell
+  that lets the document scroll, with `scroll="container"` for a full-height
+  screen. 0.27.0.
 - **DataTable server-side data** — hand the table one page from your loader
   (`manual`): no client paging or sorting, `v-model:sorting` and
   `v-model:row-selection` by row id (`getRowId`), a footer with "41–60 of 133"
@@ -106,7 +134,8 @@ Nothing in progress right now; see Next.
   form, date fields that disable chosen days, `SliderField` ticks and
   leading/trailing content, a presence status on `Avatar`, a logo slot on the
   QR code, slots on `AccordionCard`, an option slot on `SelectField`, Monaco's
-  own options on `CodeEditor` and a line variant for `Tabs`. 0.25.0.
+  own options on `CodeEditor` and a line variant for `Tabs` (`line` is now a
+  deprecated alias of `segmented`). 0.25.0.
 - **DateRangeField presets and time** — one-click ranges such as Today, Last 7
   days and This month, or your own, beside the calendar (`presets`), and a time
   of day on each end of the range (`with-time`), and `min-date` / `max-date`.