@malva-ui/core 0.1.13 → 0.1.14

package/docs/ai/switch.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The Switch library (`@malva-ui/core/switch`) provides accessible toggle switch components implementing the WAI-ARIA switch pattern. Supports grouped switches with keyboard navigation and reactive forms integration via `ControlValueAccessor`.
+The Switch library (`@malva-ui/core/switch`) provides accessible toggle switch components implementing the WAI-ARIA switch pattern. Supports grouped switches with keyboard navigation, signal-forms integration, and the shared five-level density system (`tight` / `compact` / `comfortable` / `spacious` / `airy`) from `@malva-ui/cdk/density`.
 
 > **Host `aria-label` / `aria-labelledby` forwarding** — a consumer writing
 > `<mlv-switch aria-label="Enable feature" />` (a switch with no projected text)
@@ -52,14 +52,15 @@ Exported from `@malva-ui/core/switch`:
 
 #### Inputs
 
-| Name             | Type                  | Default     | Description                                                                                                                                                                                                                                      |
-| ---------------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `disabled`       | `boolean`             | `false`     | Component-level disabled                                                                                                                                                                                                                         |
-| `state`          | `MlvSwitchState`      | `'default'` | Semantic state for track color                                                                                                                                                                                                                   |
-| `label`          | `string`              | `''`        | **Visible** label text, rendered inside the `<label>` when nothing is projected into `<mlv-switch>`. Projected content always wins (CSS `display: none`-s the fallback), so the accessible name never duplicates. Inherited from the signal base |
-| `required`       | `boolean` (coerced)   | `false`     | Sets `aria-required` on the native input; also a signal-forms field binding. Inherited from the signal base                                                                                                                                      |
-| `ariaLabel`      | `string \| null`      | `null`      | Accessible name applied to the inner native input; wins over a captured static host `aria-label`. Inherited from the signal base since 2026-08 (was a switch-local input)                                                                        |
-| `ariaLabelledBy` | `string \| undefined` | `undefined` | Id reference(s) naming the inner native input; same precedence as `ariaLabel`                                                                                                                                                                    |
+| Name             | Type                  | Default                     | Description                                                                                                                                                                                                                                                                                                                  |
+| ---------------- | --------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mlvDensity`     | `MlvDensity`          | inherited / `'comfortable'` | Density override for this switch (via the `MlvDensityDirective` host directive). All five levels scale track size, thumb size, thumb travel, label gap and label typography. Falls back to the nearest ancestor `MLV_DENSITY_CONTEXT` (e.g. an enclosing `mlv-switch-group` or `form[mlvForm]`), then to `MlvDensityService` |
+| `disabled`       | `boolean`             | `false`                     | Component-level disabled                                                                                                                                                                                                                                                                                                     |
+| `state`          | `MlvSwitchState`      | `'default'`                 | Semantic state for track color                                                                                                                                                                                                                                                                                               |
+| `label`          | `string`              | `''`                        | **Visible** label text, rendered inside the `<label>` when nothing is projected into `<mlv-switch>`. Projected content always wins (CSS `display: none`-s the fallback), so the accessible name never duplicates. Inherited from the signal base                                                                             |
+| `required`       | `boolean` (coerced)   | `false`                     | Sets `aria-required` on the native input; also a signal-forms field binding. Inherited from the signal base                                                                                                                                                                                                                  |
+| `ariaLabel`      | `string \| null`      | `null`                      | Accessible name applied to the inner native input; wins over a captured static host `aria-label`. Inherited from the signal base since 2026-08 (was a switch-local input)                                                                                                                                                    |
+| `ariaLabelledBy` | `string \| undefined` | `undefined`                 | Id reference(s) naming the inner native input; same precedence as `ariaLabel`                                                                                                                                                                                                                                                |
 
 #### Inputs (inherited from `MlvSignalFormUiControlBase`)
 
@@ -87,6 +88,8 @@ Exported from `@malva-ui/core/switch`:
 #### Host Bindings
 
 ```ts
+hostDirectives: [{ directive: MlvDensityDirective, inputs: ['mlvDensity'] }],
+providers: [{ provide: MLV_DENSITY_ELEMENT, useValue: 'switch' }, /* … */],
 host: {
   'class': 'mlv-switch',
   '[class.mlv-switch--disabled]': 'computedDisabled()',
@@ -94,6 +97,10 @@ host: {
 }
 ```
 
+`MlvDensityDirective` additionally stamps exactly one of
+`mlv-switch--tight | --compact | --comfortable | --spacious | --airy` on the host
+(from `MLV_DENSITY_ELEMENT: 'switch'`). Consumers set `mlvDensity`, never the class.
+
 The host is **not** focusable. The single focus target is the visually-hidden
 native `<input type="checkbox" role="switch">` (kept in the a11y tree via the
 clip-path pattern). Its `tabindex` is the roving tabindex managed by
@@ -133,10 +140,61 @@ A dev-mode `console.warn` fires once per instance when a switch has no projected
 
 #### Styles
 
-- Track: `40px × 24px`, `border-radius: 12px`
-- Thumb: `20px × 20px`, animates `translateX(16px)` when checked
-- Transition: `0.2s ease-in-out`
-- Uses `--mlv-border-normal`, `--mlv-background-accent-1`, `--mlv-background-base`
+Track is a stadium (`--mlv-radius-full`) at every step; the thumb is a circle
+inset by `--mlv-switch-thumb-inset` (`0.125rem`, constant). Colors:
+`--mlv-background-neutral-1` (off) → `--mlv-background-accent-1` (on),
+thumb `--mlv-elevation-bg-5` + `--mlv-shadow-1`, focus ring `--mlv-border-focus`
+promoted from the hidden input onto `.mlv-switch__track`.
+
+**2026-08-26:** in dark theme `--mlv-elevation-bg-5` follows the general
+elevation ladder (lightened grey, `color-mix` toward white off
+`--mlv-palette-neutral-700`, ≈`#707070`) — muddy against the off-track
+(≈`#262626`) and near-unreadable (≈1.07:1) against the accent-1 on-track
+(`#5770cb`). `switch.scss` shadows the token locally under
+`[mlvTheme='dark'] .mlv-switch` to `--mlv-palette-neutral-50` (≈`#fafafa`,
+same invariant near-white in every theme) so the thumb reads as a crisp knob
+in both states (14.5:1 off-track, 4.45:1 on-track). Light is untouched — it
+already resolved `--mlv-elevation-bg-5` → `--mlv-background-raised` →
+`#ffffff`. No other `--mlv-elevation-bg-5` consumer exists, so the shadowed
+override is switch-local by construction.
+
+##### Density geometry ladder
+
+Every level satisfies `thumb = track-height − 2 × inset` and
+`travel = track-width − thumb − 2 × inset`, so the thumb never clips the track.
+`comfortable` reproduces the pre-density rendering exactly.
+
+| Level         | Track (w × h)       | Thumb      | Travel     | Label gap           | Label type                                         |
+| ------------- | ------------------- | ---------- | ---------- | ------------------- | -------------------------------------------------- |
+| `tight`       | `2rem × 1.125rem`   | `0.875rem` | `0.875rem` | `--mlv-spacing-1`   | `body-s` / `--mlv-line-height-tight`               |
+| `compact`     | `2.25rem × 1.25rem` | `1rem`     | `1rem`     | `--mlv-spacing-1-5` | `body-m` / `--mlv-line-height-normal`              |
+| `comfortable` | `2.5rem × 1.5rem`   | `1.25rem`  | `1rem`     | `--mlv-spacing-2`   | `body-m` / `--mlv-line-height-normal`              |
+| `spacious`    | `3rem × 1.75rem`    | `1.5rem`   | `1.25rem`  | `--mlv-spacing-2-5` | `body-l` / `--mlv-line-height-normal`              |
+| `airy`        | `3.5rem × 2rem`     | `1.75rem`  | `1.5rem`   | `--mlv-spacing-3`   | `--mlv-font-size-xl` / `--mlv-line-height-relaxed` |
+
+The values live in component-scoped custom properties on `.mlv-switch`
+(`--mlv-switch-track-width`, `--mlv-switch-track-height`, `--mlv-switch-thumb-size`,
+`--mlv-switch-thumb-inset`, `--mlv-switch-thumb-travel`, `--mlv-switch-gap`,
+`--mlv-switch-font-size`, `--mlv-switch-line-height`), redeclared inside the five
+`density.density-*` mixin blocks.
+
+**2026-08-26:** `compact` and `airy` previously read `body-s` / `body-l` —
+one step below the shared control-text ramp (CH-R3), which put a switch
+label at a different size than an input's text at those two densities.
+Retuned to `body-m` (compact) and the primitive `--mlv-font-size-xl` (airy —
+there is no `--mlv-typography-body-xl-size` alias) to match
+`--form-ctrl-font-size`'s ramp in `mlv-form-control-wrapper`. `tight` /
+`comfortable` / `spacious` were already correct. See
+`.claude/projects/libs-form-utils.md` → _Control-text type & padding ramp_.
+
+##### Accessibility floor
+
+The pointer target is the wrapping `<label>`, not the track. `.mlv-switch__label`
+carries an unconditional `min-block-size: 1.5rem; min-inline-size: 1.5rem`, so the
+hit area never falls below **24 × 24 CSS px** (WCAG 2.2 SC 2.5.8, level AA) even
+at `tight` / `compact`, where the _visible_ track is only 18px / 20px tall.
+Label text uses `--mlv-text-primary` at every step, so contrast stays AA including
+at the 12px `body-s` used by `tight` and `compact`.
 
 ---
 
@@ -150,10 +208,11 @@ A dev-mode `console.warn` fires once per instance when a switch has no projected
 
 #### Inputs
 
-| Name    | Type                  | Default     |
-| ------- | --------------------- | ----------- |
-| `label` | `string`              | `''`        |
-| `state` | `MlvSwitchGroupState` | `'default'` |
+| Name         | Type                  | Default                     | Description                                                                                                                                                                      |
+| ------------ | --------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`      | `string`              | `''`                        | Accessible name + visible group label.                                                                                                                                           |
+| `state`      | `MlvSwitchGroupState` | `'default'`                 | Visual/validation state applied to the group.                                                                                                                                    |
+| `mlvDensity` | `MlvDensity`          | inherited / `'comfortable'` | Density for the group **and** every projected switch — see _Density projection_ below. Scales the group's inter-switch gap and is provided as `MLV_DENSITY_CONTEXT` to children. |
 
 #### Methods (inherited from `MlvFocusableGroupBase`)
 
@@ -164,9 +223,35 @@ A dev-mode `console.warn` fires once per instance when a switch has no projected
 
 #### Keyboard Navigation
 
+#### Density projection
+
+```ts
+hostDirectives: [{ directive: MlvDensityDirective, inputs: ['mlvDensity'] }],
+providers: [
+  { provide: MLV_DENSITY_ELEMENT, useValue: 'switch-group' },
+  provideMlvDensityContext(MlvDensityDirective),
+],
+```
+
+- The host is stamped `mlv-switch-group--{density}`, which scales
+  `--mlv-switch-group-gap` (`tight` `--mlv-spacing-1` → `airy` `--mlv-spacing-4`;
+  `comfortable` keeps the historical `0.5rem`).
+- `provideMlvDensityContext` publishes the group's resolved density as
+  `MLV_DENSITY_CONTEXT`. Projected `<mlv-switch>` children resolve it through
+  their declaration-site element injector (the same path `SWITCH_GROUP` uses), so
+  they stamp the matching `mlv-switch--{density}` themselves — the density reaches
+  them through DI, not only the CSS cascade.
+- Resolution order in each child: its own `mlvDensity` input → the group's
+  `MLV_DENSITY_CONTEXT` → `MlvDensityService`. An explicit `mlvDensity` on a
+  single switch therefore overrides the group.
+
 #### Template Summary
 
-`div[role="group"][aria-label]` + optional `mlv-label` + `<ng-content>` + `(keydown)` handler.
+The **host** `<mlv-switch-group>` _is_ the group container: `class="mlv-switch-group"`,
+`role="group"`, `[attr.aria-label]="label() || null"` and the `(keydown)` handler are
+host bindings (the former inner wrapper `<div>` was removed so the BEM block and its
+density modifier live on the same element). Template: optional `mlv-label` +
+`<ng-content>`.
 
 ---
 
@@ -203,6 +288,15 @@ interface MlvSwitchGroupAccessor {
 
 <!-- Disabled -->
 <mlv-switch [disabled]="true">Locked</mlv-switch>
+
+<!-- Per-switch density -->
+<mlv-switch mlvDensity="compact">Compact toggle</mlv-switch>
+
+<!-- Group density, projected to every child; one child opts out -->
+<mlv-switch-group mlvDensity="spacious" label="Notifications">
+  <mlv-switch [(checked)]="email">Email</mlv-switch>
+  <mlv-switch [(checked)]="sms" mlvDensity="tight">SMS</mlv-switch>
+</mlv-switch-group>
 ```
 
 ---
@@ -212,5 +306,6 @@ interface MlvSwitchGroupAccessor {
 - `@angular/forms` — CVA
 - `@angular/cdk/a11y` — `FocusKeyManager`, `FocusableOption`
 - `@malva-ui/cdk/accessibility` — `MlvClick`
+- `@malva-ui/cdk/density` — `MlvDensityDirective`, `MLV_DENSITY_ELEMENT`, `provideMlvDensityContext`
 - `@malva-ui/core/form-utils` — `MlvLabel`
-- `@malva-ui/styles` — design tokens, `_mixins.scss`
+- `@malva-ui/styles` — design tokens, `_mixins.scss`, `_density.scss`

package/docs/ai/table.md

@@ -0,0 +1,69 @@
+# @malva-ui/core/table
+
+> directives, styles, tests, or public API change.
+
+  
+**Import path:** `@malva-ui/core/table`  
+**Selector:** `table[mlvTable]`
+
+Native table presentation primitives for common tables. The package enhances a
+real HTML `<table>` rather than rendering rows or owning a data source. Use
+`@malva-ui/core/data-table` for sorting, filtering, pagination, selection,
+editing, virtual scroll, and other data-grid behavior.
+
+## Public API
+
+| Export              | Kind      | Description                                                                               |
+| ------------------- | --------- | ----------------------------------------------------------------------------------------- |
+| `MlvTable`          | Component | Adds Malva table appearance, responsive modes, and density support to `<table mlvTable>`. |
+| `MlvTableRow`       | Directive | Marks a `<tr mlvTableRow>` as `main` or `secondary` for Pop In mode.                      |
+| `MlvTableCell`      | Directive | Adds shared Malva cell styling to cells carrying `mlvTableCell`.                          |
+| `MlvTableHoverable` | Type      | `false`, `'row'`, or `'cell'`.                                                            |
+
+## `MlvTable`
+
+### Inputs
+
+| Input        | Type                | Default   | Description                                                                              |
+| ------------ | ------------------- | --------- | ---------------------------------------------------------------------------------------- |
+| `bordered`   | `BooleanInput`      | `false`   | Adds an outer boundary and cell separators.                                              |
+| `responsive` | `BooleanInput`      | `false`   | Enables horizontal overflow styling for narrow viewports. Required for Pop In mode.      |
+| `popIn`      | `BooleanInput`      | `false`   | Enables the paired main/secondary row presentation at the mobile breakpoint.             |
+| `hoverable`  | `MlvTableHoverable` | `false`   | Applies pointer feedback to a whole row or individual data cells.                        |
+| `mlvDensity` | `MlvDensity`        | inherited | Applies `tight`, `compact`, `comfortable`, `spacious`, or `airy` spacing and type scale. |
+
+### Appearance classes
+
+The component adds the BEM block `mlv-table` and state modifiers for the
+selected inputs. It preserves native table roles and does not add a grid role.
+
+## Pop In markup
+
+Pop In is opt-in and requires both `[responsive]="true"` and `[popIn]="true"`.
+Each data item is represented by a pair of native rows:
+
+```html
+<tr mlvTableRow main>
+  <td mlvTableCell data-label="Name">...</td>
+</tr>
+<tr mlvTableRow secondary>
+  <td mlvTableCell colspan="2">...</td>
+</tr>
+```
+
+The main row should contain the minimum set of important or interactive cells.
+The secondary row is for supporting display-only information. On narrow
+viewports the table header is visually collapsed while remaining available to
+assistive technology, main cells show their `data-label`, and the secondary
+row becomes a quiet supporting surface. Set `colspan` to the number of cells in
+the paired main row; it is a numeric HTML attribute and does not accept a
+percentage.
+
+## Styling
+
+Styles use the `mlv-table` BEM block, shared Malva design tokens, rem units,
+and a reduced-motion fallback. `MlvTable` integrates the shared
+`MlvDensityDirective`; density changes cell padding and type scale while
+preserving the native table structure. Unmarked native rows and cells remain
+valid and retain the base table styling; the row/cell directives only provide
+styling hooks and do not change native semantics.

package/docs/ai/tabs.md

@@ -142,7 +142,7 @@ Key classes:
 
 - `.mlv-tab-group` — `display:flex; flex-direction:column` (row when `--vertical`); **`min-width: 0`**.
 - `.mlv-tab-group__header` — `display:flex; overflow:hidden`; **`min-width: 0`**. Horizontal: bottom border shadow. Vertical: right border shadow.
-- `.mlv-tab-group__indicator` — absolutely-positioned bar animated via CSS custom properties `--mlv-tab-indicator-left`, `--mlv-tab-indicator-width` (horizontal) or `--mlv-tab-indicator-top`, `--mlv-tab-indicator-height` (vertical). Duration controlled via `--mlv-tab-indicator-duration` (default `220ms`).
+- `.mlv-tab-group__indicator` — absolutely-positioned bar animated via CSS custom properties `--mlv-tab-indicator-left`, `--mlv-tab-indicator-width` (horizontal) or `--mlv-tab-indicator-top`, `--mlv-tab-indicator-height` (vertical). Duration controlled via `--mlv-tab-indicator-duration` (default `var(--mlv-duration-normal)`, 200ms).
 - `.mlv-tab-group__more-trigger` — the "More (N)" overflow button.
 - `.mlv-tab-group__body` — `flex:1; min-width:0; min-height:0`.
 
@@ -182,6 +182,7 @@ CSS variables used:
 - the `__indicator` is repurposed as the **white pill that SLIDES behind the active tab** (reusing the same `left/width | top/height` animation as the underline bar) — `background: var(--mlv-background-raised)`, `box-shadow: var(--mlv-shadow-1)`, `z-index: 0`, inset inside the track padding (`top/bottom: 0.1875rem` horizontal, `left/right: 0.1875rem` vertical), **concentric radius** `calc(var(--mlv-radius-xl) - 0.1875rem)` (track radius minus track padding);
 - each `.mlv-tab-item` gets the concentric `border-radius` + `z-index: 1` (label above the pill); **non-active hover** tints `var(--mlv-background-neutral-1-hover)` (NOT `neutral-1` — that token equals the sunken track colour, making the hover invisible); the **active** item only changes `color` to `var(--mlv-text-primary)` (the sliding pill provides its background — it is _not_ given its own `background`);
 - the `__more-trigger` mirrors the non-active item treatment (radius, `z-index: 1`, hover tint) — it never carries the pill.
+- **Dark mode:** `--mlv-background-raised` resolves darker than the boxed track's `--mlv-background-neutral-1` in dark (`#1e1e1e` vs `#262626`), which would sink the pill below the track instead of lifting it. A `[mlvTheme='dark'] .mlv-tab-group--appearance-boxed > .mlv-tab-group__header > .mlv-tab-group__indicator` override repaints the pill one step lighter, `var(--mlv-palette-neutral-700)`, mirroring `mlv-segmented`'s restored raised-pill dark treatment.
 
 **Every boxed selector uses the child combinator (`>`)** — `.mlv-tab-group--appearance-boxed > .mlv-tab-group__header > .mlv-tab-item` etc. — so a boxed group **never** restyles the tab-items/indicator of a tab-group **nested inside its panels** (e.g. demo tab-groups inside a boxed docs Examples panel). The earlier descendant-combinator version leaked boxed styling into nested underline groups; the child combinator is load-bearing, not cosmetic. Boxed composes with `--horizontal` and `--vertical` (a vertical boxed group slides the pill top/height).