mtrl 0.10.3 → 0.10.5

package/README.md

@@ -50,12 +50,12 @@ import 'mtrl/styles/base';
 
 ```tsx
 import 'mtrl/styles/base';
-import { Button, Switch, Textfield } from 'mtrl/react';
+import { Button, Switch, TextField } from 'mtrl/react';
 
 export function Signup() {
   return (
     <form>
-      <Textfield name="email" type="email" label="Email" required />
+      <TextField name="email" type="email" label="Email" required />
       <Switch name="news" defaultChecked>Newsletter</Switch>
       <Button type="submit">Sign up</Button>
     </form>
@@ -67,9 +67,9 @@ export function Signup() {
 
 ```typescript
 import 'mtrl/styles';
-import { createButton, createTextfield } from 'mtrl';
+import { createButton, createTextField } from 'mtrl';
 
-const name = createTextfield({ label: 'Name' });
+const name = createTextField({ label: 'Name' });
 const save = createButton({ text: 'Save', variant: 'filled' });
 save.disabled.disable();
 
@@ -100,7 +100,7 @@ Every component comes three ways: a factory (`createButton`), an element (`<m-bu
 | Containment | Card, Carousel, List, Divider, Dialog, Bottom sheet, Side sheet |
 | Communication | Badge, Progress, Loading indicator, Snackbar, Tooltip |
 
-The factories are exported from `mtrl`: `createButton`, `createIconButton`, `createButtonGroup`, `createSplitButton`, `createFab`, `createExtendedFab`, `createFabMenu`, `createToolbar`, `createCheckbox`, `createSwitch`, `createRadios`, `createChips` (with `createAssistChip`, `createFilterChip`, `createInputChip` and `createSuggestionChip`), `createSlider`, `createTextfield`, `createSelect`, `createSearch`, `createDatePicker`, `createTimePicker`, `createNavigationRail`, `createDrawer`, `createTabs` and `createTab`, `createMenu`, `createTopAppBar`, `createBottomAppBar`, `createCard` (with `createCardHeader`, `createCardContent`, `createCardMedia` and `createCardActions`), `createCarousel`, `createList`, `createDivider`, `createDialog`, `createBottomSheet`, `createSideSheet`, `createBadge`, `createProgress`, `createLoadingIndicator`, `createSnackbar` and `createTooltip`. Deprecated: `createSegmentedButton` and `createSegment`, replaced by `createButtonGroup` with `kind: 'connected'`.
+The factories are exported from `mtrl`: `createButton`, `createIconButton`, `createButtonGroup`, `createSplitButton`, `createFab`, `createExtendedFab`, `createFabMenu`, `createToolbar`, `createCheckbox`, `createSwitch`, `createRadios`, `createChips` (with `createAssistChip`, `createFilterChip`, `createInputChip` and `createSuggestionChip`), `createSlider`, `createTextField`, `createSelect`, `createSearch`, `createDatePicker`, `createTimePicker`, `createNavigationRail`, `createDrawer`, `createTabs` and `createTab`, `createMenu`, `createTopAppBar`, `createBottomAppBar`, `createCard` (with `createCardHeader`, `createCardContent`, `createCardMedia` and `createCardActions`), `createCarousel`, `createList`, `createDivider`, `createDialog`, `createBottomSheet`, `createSideSheet`, `createBadge`, `createProgress`, `createLoadingIndicator`, `createSnackbar` and `createTooltip`. Deprecated: `createSegmentedButton` and `createSegment`, replaced by `createButtonGroup` with `kind: 'connected'`.
 
 ## Styles
 
@@ -141,6 +141,16 @@ document.documentElement.dataset.themeMode = 'dark';
 
 Available themes: `baseline`, `ocean`, `desert`, `forest`, `sunset`, `spring`, `summer`, `autumn`, `brownbeige`, `sageivory`, `tealcaramel` and `highcontrast`. With selective styles, import the theme's entry, for example `mtrl/themes/ocean`.
 
+Every theme supports `data-theme-contrast="standard"`, `"medium"` and `"high"` on the same element as `data-theme` and `data-theme-mode`:
+
+```html
+<html data-theme="desert" data-theme-mode="dark" data-theme-contrast="high">
+```
+
+Without `data-theme-contrast`, `prefers-contrast: more` selects high contrast on every themed element independently. An explicit `standard` opts out on that element; `medium` overrides the preference too. Contrast settings do not inherit from an ancestor across a nested theme: put `data-theme-contrast` on the same element as each `data-theme`, including nested sections. For example, opting out on the root does not opt out a nested theme without its own `data-theme-contrast="standard"`.
+
+The default baseline also supports this setting without `data-theme`. On that unthemed root, both standard and higher contrast follow the OS color scheme and `.dark-theme`, ignoring `data-theme-mode`. Medium and high use M3 contrast levels 0.5 and 1.0; hand-authored themes derive them with Tonal Spot from their documented seed (falling back to their light primary), preserving their light secondary and tertiary hues and chroma. Neutral palettes come from the seed, while standard colors stay unchanged. Success, warning and info keep their existing status colors. The `highcontrast` theme is a theme in its own right and supports all three contrast settings.
+
 M3's scheme variants, generated from the baseline seed, ship as their own entries only (not in the full stylesheet): `neutral`, `vibrant`, `expressive`, `fidelity`, `content`, `monochrome`, `rainbow` and `fruit-salad`, for example `mtrl/themes/vibrant`. `schemeToTokens` (`mtrl/core/theme`) turns any M3 scheme's role colours into these tokens.
 
 Deprecated, removed in 1.0: `material` (use `baseline`), `winter` (use `ocean`), `browngreen` (use `brownbeige`) and `legacy`.

package/dist/README.md

@@ -50,12 +50,12 @@ import 'mtrl/styles/base';
 
 ```tsx
 import 'mtrl/styles/base';
-import { Button, Switch, Textfield } from 'mtrl/react';
+import { Button, Switch, TextField } from 'mtrl/react';
 
 export function Signup() {
   return (
     <form>
-      <Textfield name="email" type="email" label="Email" required />
+      <TextField name="email" type="email" label="Email" required />
       <Switch name="news" defaultChecked>Newsletter</Switch>
       <Button type="submit">Sign up</Button>
     </form>
@@ -67,9 +67,9 @@ export function Signup() {
 
 ```typescript
 import 'mtrl/styles';
-import { createButton, createTextfield } from 'mtrl';
+import { createButton, createTextField } from 'mtrl';
 
-const name = createTextfield({ label: 'Name' });
+const name = createTextField({ label: 'Name' });
 const save = createButton({ text: 'Save', variant: 'filled' });
 save.disabled.disable();
 
@@ -100,7 +100,7 @@ Every component comes three ways: a factory (`createButton`), an element (`<m-bu
 | Containment | Card, Carousel, List, Divider, Dialog, Bottom sheet, Side sheet |
 | Communication | Badge, Progress, Loading indicator, Snackbar, Tooltip |
 
-The factories are exported from `mtrl`: `createButton`, `createIconButton`, `createButtonGroup`, `createSplitButton`, `createFab`, `createExtendedFab`, `createFabMenu`, `createToolbar`, `createCheckbox`, `createSwitch`, `createRadios`, `createChips` (with `createAssistChip`, `createFilterChip`, `createInputChip` and `createSuggestionChip`), `createSlider`, `createTextfield`, `createSelect`, `createSearch`, `createDatePicker`, `createTimePicker`, `createNavigationRail`, `createDrawer`, `createTabs` and `createTab`, `createMenu`, `createTopAppBar`, `createBottomAppBar`, `createCard` (with `createCardHeader`, `createCardContent`, `createCardMedia` and `createCardActions`), `createCarousel`, `createList`, `createDivider`, `createDialog`, `createBottomSheet`, `createSideSheet`, `createBadge`, `createProgress`, `createLoadingIndicator`, `createSnackbar` and `createTooltip`. Deprecated: `createSegmentedButton` and `createSegment`, replaced by `createButtonGroup` with `kind: 'connected'`.
+The factories are exported from `mtrl`: `createButton`, `createIconButton`, `createButtonGroup`, `createSplitButton`, `createFab`, `createExtendedFab`, `createFabMenu`, `createToolbar`, `createCheckbox`, `createSwitch`, `createRadios`, `createChips` (with `createAssistChip`, `createFilterChip`, `createInputChip` and `createSuggestionChip`), `createSlider`, `createTextField`, `createSelect`, `createSearch`, `createDatePicker`, `createTimePicker`, `createNavigationRail`, `createDrawer`, `createTabs` and `createTab`, `createMenu`, `createTopAppBar`, `createBottomAppBar`, `createCard` (with `createCardHeader`, `createCardContent`, `createCardMedia` and `createCardActions`), `createCarousel`, `createList`, `createDivider`, `createDialog`, `createBottomSheet`, `createSideSheet`, `createBadge`, `createProgress`, `createLoadingIndicator`, `createSnackbar` and `createTooltip`. Deprecated: `createSegmentedButton` and `createSegment`, replaced by `createButtonGroup` with `kind: 'connected'`.
 
 ## Styles
 
@@ -141,6 +141,16 @@ document.documentElement.dataset.themeMode = 'dark';
 
 Available themes: `baseline`, `ocean`, `desert`, `forest`, `sunset`, `spring`, `summer`, `autumn`, `brownbeige`, `sageivory`, `tealcaramel` and `highcontrast`. With selective styles, import the theme's entry, for example `mtrl/themes/ocean`.
 
+Every theme supports `data-theme-contrast="standard"`, `"medium"` and `"high"` on the same element as `data-theme` and `data-theme-mode`:
+
+```html
+<html data-theme="desert" data-theme-mode="dark" data-theme-contrast="high">
+```
+
+Without `data-theme-contrast`, `prefers-contrast: more` selects high contrast on every themed element independently. An explicit `standard` opts out on that element; `medium` overrides the preference too. Contrast settings do not inherit from an ancestor across a nested theme: put `data-theme-contrast` on the same element as each `data-theme`, including nested sections. For example, opting out on the root does not opt out a nested theme without its own `data-theme-contrast="standard"`.
+
+The default baseline also supports this setting without `data-theme`. On that unthemed root, both standard and higher contrast follow the OS color scheme and `.dark-theme`, ignoring `data-theme-mode`. Medium and high use M3 contrast levels 0.5 and 1.0; hand-authored themes derive them with Tonal Spot from their documented seed (falling back to their light primary), preserving their light secondary and tertiary hues and chroma. Neutral palettes come from the seed, while standard colors stay unchanged. Success, warning and info keep their existing status colors. The `highcontrast` theme is a theme in its own right and supports all three contrast settings.
+
 M3's scheme variants, generated from the baseline seed, ship as their own entries only (not in the full stylesheet): `neutral`, `vibrant`, `expressive`, `fidelity`, `content`, `monochrome`, `rainbow` and `fruit-salad`, for example `mtrl/themes/vibrant`. `schemeToTokens` (`mtrl/core/theme`) turns any M3 scheme's role colours into these tokens.
 
 Deprecated, removed in 1.0: `material` (use `baseline`), `winter` (use `ocean`), `browngreen` (use `brownbeige`) and `legacy`.

package/dist/components/bottom-app-bar/bottom-app-bar.js

@@ -1,3 +1,4 @@
+import { processClassNames } from "../../core/config/component.js";
 import { createBase, withElement, withEvents, withLifecycle, } from "../../core/compose/index.js";
 import { createConfig } from "./config.js";
 export const createBottomAppBar = (config = {}) => {
@@ -17,7 +18,7 @@ export const createBottomAppBar = (config = {}) => {
             componentConfig.fabPosition === "center"
                 ? `${component.getClass("bottom-app-bar")}--fab-center`
                 : "",
-            componentConfig.class,
+            processClassNames(componentConfig.className || ""),
         ].filter((name) => Boolean(name)),
         attributes: {
             role: "toolbar",

package/dist/components/bottom-app-bar/index.d.ts

@@ -5,4 +5,6 @@
 import { createBottomAppBar } from "./bottom-app-bar.js";
 export default createBottomAppBar;
 export { createBottomAppBar };
-export type { BottomAppBarConfig, BottomAppBar } from "./types.js";
+export type { BottomAppBarConfig, BottomAppBar as BottomAppBarComponent, 
+/** @deprecated Use BottomAppBarComponent, the name every component type has. Removed in 1.0 (FLO-383). */
+BottomAppBar, } from "./types.js";

package/dist/components/button/api.js

@@ -54,6 +54,9 @@ export const withAPI = ({ disabled, lifecycle }) => (component) => {
             disabled.enable();
             return buttonComponent;
         },
+        isDisabled() {
+            return disabled.isDisabled();
+        },
         disable() {
             disabled.disable();
             return buttonComponent;

package/dist/components/button/constants.d.ts

@@ -73,6 +73,8 @@ export declare const BUTTON_CLASSES: {
  */
 export declare const DEFAULT_RIPPLE_CONFIG: {
     readonly DURATION: 450;
+    /** @deprecated Has no effect: the option it is the default of is never applied (FLO-268). Removed in 1.0. */
     readonly TIMING: "cubic-bezier(0.4, 0.0, 0.2, 1)";
+    /** @deprecated Has no effect: the option it is the default of is never applied (FLO-268). Removed in 1.0. */
     readonly OPACITY: readonly ["0.7", "0"];
 };

package/dist/components/button/index.d.ts

@@ -4,4 +4,5 @@
  */
 export { default } from "./button.js";
 export type { ButtonConfig, ButtonComponent, ButtonVariant } from "./types.js";
+export type { ButtonEvents } from "./types.js";
 export type { ButtonSize, ButtonShape } from "./constants.js";

package/dist/components/button/types.d.ts

@@ -197,11 +197,15 @@ export interface ButtonEventPayload<E extends Event = Event> {
  * compile error rather than a listener that never fires, and a handler's
  * payload is typed rather than `any`. FLO-114.
  *
- * Only these three exist. `mount` and `unmount` are *not* here: the lifecycle
+ * Native forwarding and toggle selection are reported here. `mount` and `unmount` are *not* here: the lifecycle
  * feature keeps its own emitter and exposes them as `lifecycle.onMount` and
  * `lifecycle.onUnmount`, so they never reach `component.on`.
  */
 export interface ButtonEvents {
+    /** Selection notification from a toggle button. */
+    change: (payload: {
+        selected: boolean;
+    }) => void;
     /** The button was clicked. Not forwarded while the button is disabled. */
     click: (payload: ButtonEventPayload<MouseEvent>) => void;
     /** The button took focus. */
@@ -290,6 +294,8 @@ export interface ButtonComponent {
      * @returns The button component for chaining
      */
     disable: () => ButtonComponent;
+    /** Whether the button is disabled (FLO-384) */
+    isDisabled: () => boolean;
     /**
      * Sets the button's text content
      * @param content - Text content

package/dist/components/button-group/button-group.js

@@ -287,6 +287,9 @@ const createButtonGroup = (config = {}) => {
                 });
                 return this;
             },
+            isDisabled() {
+                return component.element.classList.contains(`${baseConfig.prefix}-button-group--disabled`);
+            },
             disable() {
                 component.element.classList.add(`${baseConfig.prefix}-button-group--disabled`);
                 buttons.forEach(button => {

package/dist/components/button-group/config.js

@@ -1,4 +1,4 @@
-import { createComponentConfig } from "../../core/config/component.js";
+import { createComponentConfig, processClassNames } from "../../core/config/component.js";
 import { cornerToken } from "../../core/theme/shape.js";
 import { BUTTON_GROUP_DEFAULTS, BUTTON_GROUP_DENSITY, BUTTON_GROUP_SIZE_TOKENS, BUTTON_GROUP_CONNECTED_GAP, BUTTON_GROUP_CONNECTED_PRESSED_CORNER, BUTTON_GROUP_DENSITY_STEP } from "./constants.js";
 export const DEFAULT_CONFIG = {
@@ -41,7 +41,7 @@ export const getContainerConfig = (config) => {
             'data-labels': labels
         },
         className: [
-            config.class,
+            processClassNames(config.className || ""),
             labels === 'selected' ? `${config.prefix}-button-group--labels-selected` : null,
             config.disabled ? `${config.prefix}-button-group--disabled` : null,
             `${config.prefix}-button-group--${orientation}`,

package/dist/components/button-group/constants.d.ts

@@ -160,9 +160,15 @@ export declare const BUTTON_GROUP_DEFAULTS: {
     readonly EQUAL_WIDTH: false;
     /** Default ripple animation duration in milliseconds */
     readonly RIPPLE_DURATION: 300;
-    /** Default ripple animation timing function */
+    /**
+     * Default ripple animation timing function
+     * @deprecated Has no effect: the option it is the default of is never applied (FLO-268). Removed in 1.0.
+     */
     readonly RIPPLE_TIMING: "cubic-bezier(0.4, 0, 0.2, 1)";
-    /** Default ripple opacity values [start, end] */
+    /**
+     * Default ripple opacity values [start, end]
+     * @deprecated Has no effect: the option it is the default of is never applied (FLO-268). Removed in 1.0.
+     */
     readonly RIPPLE_OPACITY: [string, string];
 };
 /**

package/dist/components/button-group/index.d.ts

@@ -10,4 +10,5 @@
 export { default as createButtonGroup } from "./button-group.js";
 export { default } from "./button-group.js";
 export type { ButtonGroupConfig, ButtonGroupComponent, ButtonGroupItemConfig, ButtonGroupEvent, ButtonGroupEventType, ButtonGroupVariant, ButtonGroupOrientation, ButtonGroupDensity } from "./types.js";
+export type { ButtonGroupKind, ButtonGroupSelection, ButtonGroupChangeEvent } from "./types.js";
 export { BUTTON_GROUP_VARIANTS, BUTTON_GROUP_ORIENTATIONS, BUTTON_GROUP_DENSITY, BUTTON_GROUP_EVENTS, BUTTON_GROUP_DEFAULTS, BUTTON_GROUP_CLASSES } from "./constants.js";

package/dist/components/button-group/types.d.ts

@@ -290,6 +290,8 @@ export interface ButtonGroupComponent {
      * @returns The ButtonGroupComponent for chaining
      */
     disable: () => ButtonGroupComponent;
+    /** Whether the whole group is disabled (FLO-384) */
+    isDisabled: () => boolean;
     /**
      * Enables a specific button by index
      * @param index - Button index

package/dist/components/card/index.d.ts

@@ -65,7 +65,25 @@ export { default } from "./card.js";
  *
  * These types define the structure and behavior of the Card component.
  */
-export type { CardVariant, CardElevationLevel, CardSchema, CardHeaderConfig, CardContentConfig, CardActionsConfig, CardMediaConfig, CardAriaAttributes, CardComponent, CardEvents, LoadingFeature, ExpandableFeature, SwipeableFeature, } from "./types.js";
+export type { CardVariant, CardElevationLevel, CardSchema as CardConfig, 
+/** @deprecated Use CardConfig. Removed in 1.0 (FLO-383). */
+CardSchema, CardHeaderConfig, CardContentConfig, CardActionsConfig, CardMediaConfig, CardAriaAttributes, CardComponent, CardEvents, 
+/** @deprecated Internal, no replacement: removed from mtrl/components/card in 1.0.0 (FLO-381). */
+LoadingFeature, 
+/** @deprecated Internal, no replacement: removed from mtrl/components/card in 1.0.0 (FLO-381). */
+ExpandableFeature, 
+/** @deprecated Internal, no replacement: removed from mtrl/components/card in 1.0.0 (FLO-381). */
+SwipeableFeature, } from "./types.js";
 export { createCardContent, createCardHeader, createCardActions, createCardMedia, } from "./content.js";
-export { withAPI } from "./api.js";
-export { withLoading, withExpandable, withSwipeable, withElevation, } from "./features.js";
+export { 
+/** @deprecated Internal, no replacement: removed from mtrl/components/card in 1.0.0 (FLO-381). */
+withAPI, } from "./api.js";
+export { 
+/** @deprecated Internal, no replacement: removed from mtrl/components/card in 1.0.0 (FLO-381). */
+withLoading, 
+/** @deprecated Internal, no replacement: removed from mtrl/components/card in 1.0.0 (FLO-381). */
+withExpandable, 
+/** @deprecated Internal, no replacement: removed from mtrl/components/card in 1.0.0 (FLO-381). */
+withSwipeable, 
+/** @deprecated Internal, no replacement: removed from mtrl/components/card in 1.0.0 (FLO-381). */
+withElevation, } from "./features.js";

package/dist/components/card/index.js

@@ -1,4 +1,4 @@
 export { default } from "./card.js";
 export { createCardContent, createCardHeader, createCardActions, createCardMedia, } from "./content.js";
-export { withAPI } from "./api.js";
+export { withAPI, } from "./api.js";
 export { withLoading, withExpandable, withSwipeable, withElevation, } from "./features.js";

package/dist/components/card/types.d.ts

@@ -291,6 +291,10 @@ export interface CardComponentConfig extends CardSchema {
  * a draggable one emits `dragstart` and `dragend`.
  */
 export interface CardEvents {
+    /** Presentation state after expanding or collapsing. */
+    expandedChanged: (payload: {
+        expanded: boolean;
+    }) => void;
     click: (payload: ForwardedEventPayload<MouseEvent, HTMLElement>) => void;
     mouseenter: (payload: ForwardedEventPayload<MouseEvent, HTMLElement>) => void;
     mouseleave: (payload: ForwardedEventPayload<MouseEvent, HTMLElement>) => void;
@@ -439,11 +443,23 @@ export interface CardComponent extends BaseComponent {
      * ```
      */
     destroy: () => void;
-    /** Optional loading feature */
+    /**
+     * Optional loading feature
+     * @deprecated Never set by `createCard`: only the deprecated `withLoading` feature adds it.
+     * Removed in 1.0 with that feature (FLO-381).
+     */
     loading?: LoadingFeature;
-    /** Optional expandable feature */
+    /**
+     * Optional expandable feature
+     * @deprecated Never set by `createCard`: only the deprecated `withExpandable` feature adds it.
+     * Removed in 1.0 with that feature (FLO-381).
+     */
     expandable?: ExpandableFeature;
-    /** Optional swipeable feature */
+    /**
+     * Optional swipeable feature
+     * @deprecated Never set by `createCard`: only the deprecated `withSwipeable` feature adds it.
+     * Removed in 1.0 with that feature (FLO-381).
+     */
     swipeable?: SwipeableFeature;
 }
 /**

package/dist/components/carousel/api.d.ts

@@ -9,6 +9,7 @@ interface ApiComponent {
     next: () => void;
     prev: () => void;
     goTo: (index: number) => void;
+    setWheel: (on: boolean) => void;
     lifecycle?: {
         destroy: () => void;
     };

package/dist/components/carousel/api.js

@@ -16,6 +16,10 @@ export const withAPI = () => (component) => {
             component.goTo(index);
             return api;
         },
+        setWheel(on) {
+            component.setWheel(on);
+            return api;
+        },
         getCurrentSlide: () => component.getCurrentSlide(),
         getVariant: () => component.getVariant(),
         addSlide(slide, index) {

package/dist/components/carousel/features/scroll.d.ts

@@ -6,6 +6,7 @@ interface ScrollComponent {
     next: () => void;
     prev: () => void;
     goTo: (index: number) => void;
+    setWheel: (on: boolean) => void;
     lifecycle: {
         destroy: () => void;
     };

package/dist/components/carousel/features/scroll.js

@@ -5,6 +5,7 @@ import { multiBrowseKeylines, heroKeylines, uncontainedKeylines, fullScreenKeyli
 import { createStrategy, keylinesForScrollOffset, snapPositionOffset, maxScrollOffset, placeItem, } from "../strategy.js";
 const FLING_VELOCITY = 0.4;
 const DRAG_THRESHOLD = 4;
+const WHEEL_QUIET = 120;
 export const withScroll = (config) => (component) => {
     const { variant, gap, padding, snap } = resolveLayoutDefaults(config);
     const vertical = variant === CAROUSEL_VARIANTS.FULL_SCREEN;
@@ -25,6 +26,7 @@ export const withScroll = (config) => (component) => {
     const prefix = component.getClass("carousel");
     const snapClass = `${prefix}__snap`;
     element.classList.toggle(`${prefix}--snap`, snap);
+    let lastWheel = -Infinity;
     let strategy = null;
     let count = 0;
     let containerSize = 0;
@@ -172,6 +174,7 @@ export const withScroll = (config) => (component) => {
         }
     };
     const rebuild = () => {
+        stopWheel();
         build();
         if (strategy) {
             expect(currentIndex);
@@ -180,6 +183,7 @@ export const withScroll = (config) => (component) => {
         layout();
     };
     const goTo = (index) => {
+        stopWheel();
         if (!count)
             return;
         const target = Math.min(Math.max(index, 0), count - 1);
@@ -199,6 +203,7 @@ export const withScroll = (config) => (component) => {
         return item ? slideElements.indexOf(item) : -1;
     };
     const handleKeyDown = (e) => {
+        stopWheel();
         const from = indexOf(e.target);
         if (from < 0)
             return;
@@ -238,10 +243,12 @@ export const withScroll = (config) => (component) => {
         delete element.dataset.settling;
     };
     const handlePointerDown = (e) => {
+        stopWheel();
         clearPending();
         if (e.pointerType !== "mouse" || e.button !== 0 || !strategy)
             return;
         dragging = true;
+        lastWheel = -Infinity;
         dragged = false;
         dragStart = vertical ? e.clientY : e.clientX;
         dragLast = dragStart;
@@ -304,9 +311,115 @@ export const withScroll = (config) => (component) => {
             e.stopPropagation();
         }
     };
+    let wheelDirection = 0;
+    let wheelStart = 0;
+    let wheelDelta = 0;
+    let wheelTarget = 0;
+    let wheelFrame = 0;
+    let wheelPosition = 0;
+    let wheelVelocity = 0;
+    let wheelTime = 0;
+    let wheelSnap = null;
+    let wheelSnapPriority = "";
+    const stopWheel = (resetGesture = true) => {
+        if (wheelFrame)
+            window.cancelAnimationFrame(wheelFrame);
+        wheelFrame = 0;
+        wheelVelocity = 0;
+        if (resetGesture)
+            lastWheel = -Infinity;
+        if (wheelSnap !== null) {
+            scroller.style.setProperty("scroll-snap-type", wheelSnap, wheelSnapPriority);
+            wheelSnap = null;
+            clearPending();
+        }
+    };
+    const glide = (now) => {
+        const dt = (now - wheelTime) / 1000;
+        wheelTime = now;
+        const offset = wheelPosition - wheelTarget;
+        const decay = Math.exp(-12 * dt);
+        const carry = wheelVelocity + 12 * offset;
+        wheelPosition = wheelTarget + (offset + carry * dt) * decay;
+        wheelVelocity = (wheelVelocity - 12 * carry * dt) * decay;
+        const resting = wheelDirection * (wheelPosition - wheelTarget) >= 0 ||
+            (Math.abs(wheelPosition - wheelTarget) < 0.5 && Math.abs(wheelVelocity) < 5);
+        scroller.scrollLeft = resting ? wheelTarget : wheelPosition;
+        if (resting)
+            stopWheel(false);
+        else
+            wheelFrame = window.requestAnimationFrame(glide);
+    };
+    const handleTouchStart = () => {
+        stopWheel();
+        clearPending();
+    };
+    const handleWheel = (e) => {
+        if (e.ctrlKey || dragging || Math.abs(e.deltaX) >= Math.abs(e.deltaY) || !strategy)
+            return;
+        const position = scrollPosition();
+        const end = snapPositions[count - 1] ?? 0;
+        const direction = Math.sign(e.deltaY);
+        if (direction < 0 ? position <= 1 : position >= end - 1)
+            return;
+        e.preventDefault();
+        if (direction !== wheelDirection)
+            stopWheel();
+        if (e.timeStamp - lastWheel >= WHEEL_QUIET || direction !== wheelDirection) {
+            wheelStart = position;
+            wheelDelta = 0;
+            wheelTarget = position;
+        }
+        lastWheel = e.timeStamp;
+        wheelDirection = direction;
+        const unit = e.deltaMode === 1
+            ? parseFloat(window.getComputedStyle(scroller).lineHeight) || 16
+            : e.deltaMode === 2 ? containerSize : 1;
+        wheelDelta += e.deltaY * unit;
+        const destination = Math.max(0, Math.min(end, wheelStart + wheelDelta));
+        let index = direction > 0 ? count - 1 : 0;
+        for (let i = direction > 0 ? 0 : count - 1; i >= 0 && i < count; i += direction) {
+            if (direction * (snapPositions[i] - destination) >= 0 &&
+                direction * (snapPositions[i] - wheelStart) > 0) {
+                index = i;
+                break;
+            }
+        }
+        const target = snapPositions[index];
+        if (direction * (target - wheelTarget) > 0) {
+            wheelTarget = target;
+            expect(index);
+            if (reduceMotion?.matches) {
+                setScrollPosition(target, false);
+            }
+            else if (!wheelFrame) {
+                wheelSnap = scroller.style.getPropertyValue("scroll-snap-type");
+                wheelSnapPriority = scroller.style.getPropertyPriority("scroll-snap-type");
+                scroller.style.setProperty("scroll-snap-type", "none");
+                scroller.scrollLeft = position;
+                wheelPosition = position;
+                wheelTime = performance.now();
+                wheelFrame = window.requestAnimationFrame(glide);
+            }
+            if (index !== currentIndex) {
+                currentIndex = index;
+                emitChange();
+            }
+        }
+        else {
+            expect(currentIndex);
+        }
+    };
+    const setWheel = (on) => {
+        scroller.removeEventListener("wheel", handleWheel);
+        stopWheel();
+        if (on && !vertical)
+            scroller.addEventListener("wheel", handleWheel, { passive: false });
+    };
     scroller.addEventListener("scroll", layout, { passive: true });
     scroller.addEventListener("wheel", clearPending, { passive: true });
-    scroller.addEventListener("touchstart", clearPending, { passive: true });
+    setWheel(!!config.wheel);
+    scroller.addEventListener("touchstart", handleTouchStart, { passive: true });
     scroller.addEventListener("keydown", handleKeyDown);
     scroller.addEventListener("focusin", handleFocusIn);
     scroller.addEventListener("pointerdown", handlePointerDown);
@@ -326,15 +439,17 @@ export const withScroll = (config) => (component) => {
     enhanced.next = next;
     enhanced.prev = prev;
     enhanced.goTo = goTo;
+    enhanced.setWheel = setWheel;
     enhanced.lifecycle = {
         destroy: () => {
+            setWheel(false);
             restoreSnap();
             resizeObserver?.disconnect();
             reduceMotion?.removeEventListener?.("change", rebuild);
             clearPending();
             scroller.removeEventListener("scroll", layout);
             scroller.removeEventListener("wheel", clearPending);
-            scroller.removeEventListener("touchstart", clearPending);
+            scroller.removeEventListener("touchstart", handleTouchStart);
             scroller.removeEventListener("keydown", handleKeyDown);
             scroller.removeEventListener("focusin", handleFocusIn);
             scroller.removeEventListener("pointerdown", handlePointerDown);

package/dist/components/carousel/types.d.ts

@@ -43,6 +43,14 @@ export interface CarouselConfig {
     cornerRadius?: number;
     /** Snap to items after scrolling; on by default except for uncontained layouts */
     snap?: boolean;
+    /**
+     * Scroll horizontal carousels with a vertical mouse wheel; false by default.
+     * Normalized deltas accumulate per gesture and glide to directional snap points.
+     * One notch advances at least one item; momentum can pass several whole items.
+     * At either edge the page scrolls.
+     * Horizontal trackpad gestures, zoom and vertical layouts stay native.
+     */
+    wheel?: boolean;
     initialSlide?: number;
     minSmallItemWidth?: number;
     maxSmallItemWidth?: number;
@@ -64,6 +72,8 @@ export interface CarouselComponent {
     goTo: (index: number) => CarouselComponent;
     getCurrentSlide: () => number;
     getVariant: () => CarouselVariant;
+    /** Enable or disable vertical mouse wheel scrolling in place. */
+    setWheel: (on: boolean) => CarouselComponent;
     addSlide: (slide: CarouselSlide, index?: number) => CarouselComponent;
     removeSlide: (index: number) => CarouselComponent;
     destroy: () => void;

package/dist/components/checkbox/api.js

@@ -76,6 +76,9 @@ export const withAPI = ({ disabled, lifecycle, checkable }) => (component) => ({
         disabled.enable();
         return this;
     },
+    isDisabled() {
+        return disabled.isDisabled();
+    },
     disable() {
         disabled.disable();
         return this;

package/dist/components/checkbox/config.js

@@ -43,6 +43,7 @@ export const getApiConfig = (comp) => ({
     disabled: {
         enable: comp.disabled.enable,
         disable: comp.disabled.disable,
+        isDisabled: comp.disabled.isDisabled,
     },
     lifecycle: {
         destroy: comp.lifecycle.destroy,

package/dist/components/checkbox/types.d.ts

@@ -6,6 +6,8 @@ import type { EventCallback } from "../../core/state/emitter.js";
  * @remarks
  * - filled: Checkbox with filled background when checked (default)
  * - outlined: Checkbox with outline only, for less visual emphasis
+ * @deprecated The type of the deprecated `variant` option, which has no effect: M3 has one
+ * checkbox style (FLO-94, FLO-265). Removed in 1.0.
  */
 export type CheckboxVariant = "filled" | "outlined";
 /**
@@ -104,13 +106,13 @@ export interface CheckboxConfig {
      */
     componentName?: string;
 }
-/** A checked-state change from the native input or a programmatic setter. */
+/** A checked-state change from native input activation. Public setters are silent. */
 export interface CheckboxChangePayload {
     /** The new checked state. */
     checked: boolean;
     /** The input's HTML value attribute, not the boolean checked state. */
     value: string;
-    /** Present for input-driven changes; absent for check/uncheck/toggle/setValue. */
+    /** The original native change event, when supplied by the emitter. */
     nativeEvent?: Event;
 }
 /** Events emitted by the checkbox API. DOM clicks/focus are not forwarded. */
@@ -231,6 +233,8 @@ export interface CheckboxComponent {
      * @returns Checkbox component for method chaining
      */
     disable: () => CheckboxComponent;
+    /** Whether the checkbox is disabled (FLO-384) */
+    isDisabled: () => boolean;
     /**
      * Destroys the checkbox component and cleans up resources
      * Removes event listeners and DOM references
@@ -246,6 +250,7 @@ export interface ApiOptions {
     disabled: {
         enable: () => void;
         disable: () => void;
+        isDisabled: () => boolean;
     };
     lifecycle: {
         destroy: () => void;
@@ -278,6 +283,7 @@ export interface BaseComponent {
     disabled?: {
         enable: () => void;
         disable: () => void;
+        isDisabled: () => boolean;
     };
     lifecycle?: {
         destroy: () => void;