mtrl 0.7.0 → 0.8.0-next.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/dist/components/button/api.d.ts +4 -0
  2. package/dist/components/button/features/toggle.d.ts +42 -0
  3. package/dist/components/button/types.d.ts +30 -0
  4. package/dist/components/button-group/button-group.d.ts +6 -4
  5. package/dist/components/button-group/config.d.ts +15 -7
  6. package/dist/components/button-group/constants.d.ts +85 -17
  7. package/dist/components/button-group/index.d.ts +1 -1
  8. package/dist/components/button-group/types.d.ts +68 -4
  9. package/dist/components/carousel/api.d.ts +11 -30
  10. package/dist/components/carousel/arrangement.d.ts +23 -0
  11. package/dist/components/carousel/carousel.d.ts +13 -63
  12. package/dist/components/carousel/config.d.ts +2 -31
  13. package/dist/components/carousel/constants.d.ts +25 -151
  14. package/dist/components/carousel/features/index.d.ts +2 -5
  15. package/dist/components/carousel/features/scroll.d.ts +19 -0
  16. package/dist/components/carousel/features/slides.d.ts +18 -8
  17. package/dist/components/carousel/index.d.ts +3 -37
  18. package/dist/components/carousel/keylines.d.ts +65 -0
  19. package/dist/components/carousel/strategy.d.ts +36 -0
  20. package/dist/components/carousel/types.d.ts +36 -242
  21. package/dist/components/dialog/api.d.ts +1 -1
  22. package/dist/components/index.d.ts +2 -0
  23. package/dist/components/slider/constants.d.ts +8 -8
  24. package/dist/components/slider/types.d.ts +4 -1
  25. package/dist/components/snackbar/api.d.ts +1 -1
  26. package/dist/components/snackbar/config.d.ts +2 -1
  27. package/dist/components/snackbar/constants.d.ts +18 -0
  28. package/dist/components/snackbar/index.d.ts +2 -1
  29. package/dist/components/snackbar/queue.d.ts +10 -2
  30. package/dist/components/snackbar/types.d.ts +37 -1
  31. package/dist/index.cjs +20 -10
  32. package/dist/index.cjs.map +54 -38
  33. package/dist/index.js +20 -10
  34. package/dist/index.js.map +54 -38
  35. package/dist/package.json +1 -1
  36. package/dist/styles.css +2 -2
  37. package/package.json +3 -6
  38. package/src/styles/abstract/_theme.scss +4 -2
  39. package/src/styles/abstract/_variables.scss +59 -12
  40. package/src/styles/components/_button-group.scss +122 -349
  41. package/src/styles/components/_button.scss +333 -591
  42. package/src/styles/components/_carousel.scss +131 -611
  43. package/src/styles/components/_icon-button.scss +23 -23
  44. package/src/styles/components/_select.scss +9 -1
  45. package/src/styles/components/_slider.scss +10 -9
  46. package/src/styles/themes/_index.scss +1 -0
  47. package/src/styles/themes/_legacy.scss +73 -0
  48. package/dist/components/carousel/features/drag.d.ts +0 -8
@@ -37,6 +37,10 @@ interface ComponentWithElements {
37
37
  on?: (event: string, handler: Function) => ComponentWithElements;
38
38
  off?: (event: string, handler: Function) => ComponentWithElements;
39
39
  addClass?: (...classes: string[]) => ComponentWithElements;
40
+ toggle?: {
41
+ setSelected: (selected: boolean) => void;
42
+ isSelected: () => boolean;
43
+ };
40
44
  progress?: ProgressComponent;
41
45
  showProgress?: () => Promise<ComponentWithElements>;
42
46
  showProgressSync?: () => ComponentWithElements;
@@ -0,0 +1,42 @@
1
+ import { ButtonConfig } from "../types";
2
+ /**
3
+ * Toggle state manager
4
+ * @category Components
5
+ */
6
+ export interface ToggleManager {
7
+ /** Sets the selected state */
8
+ setSelected: (selected: boolean) => void;
9
+ /** Whether the button is selected */
10
+ isSelected: () => boolean;
11
+ }
12
+ /**
13
+ * Component with the elements the toggle feature needs
14
+ * @internal
15
+ */
16
+ interface ToggleableComponent {
17
+ element: HTMLElement;
18
+ getClass: (name: string) => string;
19
+ emit?: (event: string, data?: unknown) => unknown;
20
+ }
21
+ /**
22
+ * Component enhanced with toggle capabilities
23
+ * @category Components
24
+ */
25
+ export interface ToggleComponent {
26
+ toggle: ToggleManager;
27
+ }
28
+ /**
29
+ * Turns a button into an M3 toggle button: a click flips the selected
30
+ * state, the element carries `aria-pressed`, and the `--toggle` and
31
+ * `--selected` classes drive the selected colours and the shape swap.
32
+ *
33
+ * Emits a `change` event with `{ selected }` when the user toggles it.
34
+ * With `toggleOnClick: false` the click does nothing and a container
35
+ * (button group) drives the state through `setSelected`.
36
+ *
37
+ * @param config - Button configuration (`toggle`, `selected`, `toggleOnClick`)
38
+ * @returns Component enhancer
39
+ * @category Components
40
+ */
41
+ export declare const withToggle: (config: ButtonConfig) => <C extends ToggleableComponent>(component: C) => C & Partial<ToggleComponent>;
42
+ export {};
@@ -106,6 +106,25 @@ export interface ButtonConfig extends BaseComponentConfig {
106
106
  * @default false
107
107
  */
108
108
  showProgress?: boolean;
109
+ /**
110
+ * Makes the button a toggle button: a click flips its selected state,
111
+ * the element carries aria-pressed, and the selected state uses the M3
112
+ * toggle colours and swaps the resting shape (round to square, square
113
+ * to round). Text buttons have no toggle style.
114
+ * @default false
115
+ */
116
+ toggle?: boolean;
117
+ /**
118
+ * Initial selected state of a toggle button
119
+ * @default false
120
+ */
121
+ selected?: boolean;
122
+ /**
123
+ * Whether a click flips the selected state of a toggle button. Set to
124
+ * false when a container (button group) owns the selection.
125
+ * @default true
126
+ */
127
+ toggleOnClick?: boolean;
109
128
  }
110
129
  /**
111
130
  * Icon API interface for managing button icons
@@ -276,6 +295,17 @@ export interface ButtonComponent {
276
295
  * @returns The button component for chaining
277
296
  */
278
297
  setActive: (active: boolean) => ButtonComponent;
298
+ /**
299
+ * Sets the selected state of a toggle button (no-op unless `toggle` is set)
300
+ * @param selected - Whether the button is selected
301
+ * @returns The button component for chaining
302
+ */
303
+ setSelected: (selected: boolean) => ButtonComponent;
304
+ /**
305
+ * Whether a toggle button is selected
306
+ * @returns true when selected, false otherwise or when not a toggle button
307
+ */
308
+ isSelected: () => boolean;
279
309
  /**
280
310
  * Adds an event listener to the button
281
311
  * @param event - Event name ('click', 'focus', etc.)
@@ -7,11 +7,13 @@ import { ButtonGroupConfig, ButtonGroupComponent } from './types';
7
7
  * related actions where each button triggers an independent action.
8
8
  *
9
9
  * Per Material Design 3 specifications:
10
- * - Buttons are visually connected with shared borders
11
- * - Only outer corners are rounded
12
- * - All buttons share the same variant for visual consistency
10
+ * - Standard groups space their buttons (18/12/8/8/8dp by size) and a
11
+ * pressed button briefly widens while its neighbours narrow
12
+ * - Connected groups space their buttons 2dp apart with square inner
13
+ * corners and round outer corners; a selected button becomes a pill
14
+ * - All buttons share the same variant, size and shape
13
15
  * - Supports horizontal and vertical orientations
14
- * - Supports density scaling
16
+ * - Supports density scaling (4dp per step)
15
17
  *
16
18
  * @param {ButtonGroupConfig} config - Button Group configuration
17
19
  * @returns {ButtonGroupComponent} Button Group component instance
@@ -1,4 +1,4 @@
1
- import { ButtonGroupConfig, ButtonGroupVariant, ButtonGroupOrientation, ButtonGroupDensity } from './types';
1
+ import { ButtonGroupConfig, ButtonGroupVariant, ButtonGroupDensity } from './types';
2
2
  /**
3
3
  * Default configuration values for button groups
4
4
  * @internal
@@ -24,19 +24,23 @@ export declare const getContainerConfig: (config: ButtonGroupConfig) => {
24
24
  role: string;
25
25
  'aria-label': string;
26
26
  'data-variant': ButtonGroupVariant;
27
- 'data-orientation': ButtonGroupOrientation;
27
+ 'data-orientation': import("./types").ButtonGroupOrientation;
28
28
  'data-density': ButtonGroupDensity;
29
+ 'data-kind': import("./types").ButtonGroupKind;
30
+ 'data-selection': import("./types").ButtonGroupSelection;
31
+ 'data-shape': import("./types").ButtonGroupShape;
32
+ 'data-size': import("./types").ButtonGroupSize;
33
+ 'data-labels': import("./types").ButtonGroupLabels;
29
34
  };
30
35
  className: string[];
31
36
  interactive: boolean;
32
37
  };
33
38
  /**
34
- * Gets density-specific sizing values per MD3 specifications
35
- * @param {ButtonGroupDensity} density - The density level
36
- * @returns {Object} CSS variables with sizing values
37
- * @internal
39
+ * Size, kind and density tokens as custom properties on the container
40
+ * (Material 3 button group specs). Density lowers the container height by
41
+ * 4dp per step; the buttons follow the container height.
38
42
  */
39
- export declare const getDensityStyles: (density: ButtonGroupDensity) => Record<string, string>;
43
+ export declare const getSizeStyles: (size: ButtonGroupConfig["size"], kind: ButtonGroupConfig["kind"], density?: ButtonGroupDensity) => Record<string, string>;
40
44
  /**
41
45
  * Generates configuration for a button element within the group
42
46
  * @param {Object} buttonConfig - Button configuration
@@ -48,6 +52,8 @@ export declare const getDensityStyles: (density: ButtonGroupDensity) => Record<s
48
52
  */
49
53
  export declare const getButtonConfig: (buttonConfig: ButtonGroupConfig["buttons"][number], index: number, total: number, groupConfig: ButtonGroupConfig) => {
50
54
  variant: ButtonGroupVariant;
55
+ size: import("./types").ButtonGroupSize;
56
+ shape: import("./types").ButtonGroupShape;
51
57
  disabled: boolean;
52
58
  ripple: boolean;
53
59
  rippleConfig: {
@@ -61,6 +67,8 @@ export declare const getButtonConfig: (buttonConfig: ButtonGroupConfig["buttons"
61
67
  icon?: string;
62
68
  ariaLabel?: string;
63
69
  value?: string;
70
+ selectedIcon?: string;
71
+ selected?: boolean;
64
72
  };
65
73
  /**
66
74
  * Maps variant name to button variant
@@ -45,11 +45,96 @@ export declare const BUTTON_GROUP_EVENTS: {
45
45
  readonly FOCUS: "focus";
46
46
  /** Fired when a button loses focus */
47
47
  readonly BLUR: "blur";
48
+ /** Fired when the selection changes (selection groups) */
49
+ readonly CHANGE: "change";
48
50
  };
51
+ /** Material 3 button group kinds */
52
+ export declare const BUTTON_GROUP_KINDS: {
53
+ readonly STANDARD: "standard";
54
+ readonly CONNECTED: "connected";
55
+ };
56
+ /** Selection behaviour of the group */
57
+ export declare const BUTTON_GROUP_SELECTION: {
58
+ readonly NONE: "none";
59
+ readonly SINGLE: "single";
60
+ readonly MULTI: "multi";
61
+ };
62
+ export declare const BUTTON_GROUP_SHAPES: {
63
+ readonly ROUND: "round";
64
+ readonly SQUARE: "square";
65
+ };
66
+ export declare const BUTTON_GROUP_SIZES: {
67
+ readonly XS: "xs";
68
+ readonly S: "s";
69
+ readonly M: "m";
70
+ readonly L: "l";
71
+ readonly XL: "xl";
72
+ };
73
+ /**
74
+ * Material 3 button group tokens per size (dp): container height, button
75
+ * icon size, standard between-space, connected inner corner
76
+ * (m3.material.io button group specs; ButtonGroupSmallTokens.kt and
77
+ * ConnectedButtonGroupSmallTokens.kt for the s size)
78
+ */
79
+ export declare const BUTTON_GROUP_SIZE_TOKENS: {
80
+ readonly xs: {
81
+ readonly height: 32;
82
+ readonly icon: 20;
83
+ readonly standardGap: 18;
84
+ readonly connectedCorner: 4;
85
+ };
86
+ readonly s: {
87
+ readonly height: 40;
88
+ readonly icon: 20;
89
+ readonly standardGap: 12;
90
+ readonly connectedCorner: 8;
91
+ };
92
+ readonly m: {
93
+ readonly height: 56;
94
+ readonly icon: 24;
95
+ readonly standardGap: 8;
96
+ readonly connectedCorner: 8;
97
+ };
98
+ readonly l: {
99
+ readonly height: 96;
100
+ readonly icon: 32;
101
+ readonly standardGap: 8;
102
+ readonly connectedCorner: 16;
103
+ };
104
+ readonly xl: {
105
+ readonly height: 136;
106
+ readonly icon: 40;
107
+ readonly standardGap: 8;
108
+ readonly connectedCorner: 20;
109
+ };
110
+ };
111
+ /** Connected groups use 2dp between buttons at every size */
112
+ export declare const BUTTON_GROUP_CONNECTED_GAP = 2;
113
+ /** Connected pressed inner corner: extra-small (ConnectedButtonGroupSmallTokens.PressedInnerCornerCornerSize) */
114
+ export declare const BUTTON_GROUP_CONNECTED_PRESSED_CORNER = 4;
115
+ /** Connected xs and s groups keep a 48dp minimum width per button */
116
+ export declare const BUTTON_GROUP_CONNECTED_MIN_WIDTH = 48;
117
+ /**
118
+ * Standard groups: a pressed button widens by this share of its width and
119
+ * its neighbours give up the difference (ButtonGroupDefaults.ExpandedRatio)
120
+ */
121
+ export declare const BUTTON_GROUP_EXPANDED_RATIO = 0.15;
122
+ /** Density reduces the container height by 4dp per step */
123
+ export declare const BUTTON_GROUP_DENSITY_STEP = 4;
49
124
  /**
50
125
  * Default configuration values
51
126
  */
127
+ /** Label display in selection groups */
128
+ export declare const BUTTON_GROUP_LABELS: {
129
+ readonly ALWAYS: "always";
130
+ readonly SELECTED: "selected";
131
+ };
52
132
  export declare const BUTTON_GROUP_DEFAULTS: {
133
+ readonly KIND: "standard";
134
+ readonly SELECTION: "none";
135
+ readonly SHAPE: "round";
136
+ readonly SIZE: "s";
137
+ readonly LABELS: "always";
53
138
  /** Default variant (outlined per MD3 button group specs) */
54
139
  readonly VARIANT: "outlined";
55
140
  /** Default orientation */
@@ -109,20 +194,3 @@ export declare const BUTTON_GROUP_CLASSES: {
109
194
  /** Compact density */
110
195
  readonly DENSITY_COMPACT: "button-group--density-compact";
111
196
  };
112
- /**
113
- * Density-specific height values per MD3 specifications
114
- */
115
- export declare const BUTTON_GROUP_HEIGHTS: {
116
- readonly default: 40;
117
- readonly comfortable: 36;
118
- readonly compact: 32;
119
- };
120
- /**
121
- * Border radius values per MD3 specifications
122
- * Button groups use full-rounded corners on outer edges
123
- */
124
- export declare const BUTTON_GROUP_RADII: {
125
- readonly default: 20;
126
- readonly comfortable: 18;
127
- readonly compact: 16;
128
- };
@@ -10,4 +10,4 @@
10
10
  export { default as createButtonGroup } from './button-group';
11
11
  export { default } from './button-group';
12
12
  export type { ButtonGroupConfig, ButtonGroupComponent, ButtonGroupItemConfig, ButtonGroupEvent, ButtonGroupEventType, ButtonGroupVariant, ButtonGroupOrientation, ButtonGroupDensity } from './types';
13
- export { BUTTON_GROUP_VARIANTS, BUTTON_GROUP_ORIENTATIONS, BUTTON_GROUP_DENSITY, BUTTON_GROUP_EVENTS, BUTTON_GROUP_DEFAULTS, BUTTON_GROUP_CLASSES, BUTTON_GROUP_HEIGHTS, BUTTON_GROUP_RADII } from './constants';
13
+ export { BUTTON_GROUP_VARIANTS, BUTTON_GROUP_ORIENTATIONS, BUTTON_GROUP_DENSITY, BUTTON_GROUP_EVENTS, BUTTON_GROUP_DEFAULTS, BUTTON_GROUP_CLASSES } from './constants';
@@ -18,7 +18,31 @@ export type ButtonGroupDensity = "default" | "comfortable" | "compact";
18
18
  /**
19
19
  * Event types for button group
20
20
  */
21
- export type ButtonGroupEventType = "click" | "focus" | "blur";
21
+ export type ButtonGroupEventType = "click" | "focus" | "blur" | "change";
22
+ /**
23
+ * Material 3 button group kinds.
24
+ * - "standard": padding between buttons; a selected button morphs from round
25
+ * to square and its neighbours adjust.
26
+ * - "connected": 2dp between buttons, round outer corners, square inner
27
+ * corners; selection changes only the selected button. Replaces the
28
+ * segmented button for single- and multi-select.
29
+ */
30
+ export type ButtonGroupKind = "standard" | "connected";
31
+ export type ButtonGroupSelection = "none" | "single" | "multi";
32
+ export type ButtonGroupShape = "round" | "square";
33
+ export type ButtonGroupSize = "xs" | "s" | "m" | "l" | "xl";
34
+ /** Label display: always, or only on the selected button (icon-only otherwise) */
35
+ export type ButtonGroupLabels = "always" | "selected";
36
+ /** Payload of the "change" event: the selection after the change. */
37
+ export interface ButtonGroupChangeEvent {
38
+ buttonGroup: ButtonGroupComponent;
39
+ /** Values of the selected buttons, in button order */
40
+ values: string[];
41
+ selected: ButtonComponent[];
42
+ /** The button whose click caused the change, if any */
43
+ button?: ButtonComponent;
44
+ originalEvent?: Event;
45
+ }
22
46
  /**
23
47
  * Event data for button group events
24
48
  */
@@ -67,6 +91,10 @@ export interface ButtonGroupItemConfig extends Omit<ButtonConfig, "variant"> {
67
91
  * Value associated with this button
68
92
  */
69
93
  value?: string;
94
+ /** Icon shown while selected (toggle buttons) */
95
+ selectedIcon?: string;
96
+ /** Initially selected (selection groups only) */
97
+ selected?: boolean;
70
98
  /**
71
99
  * Additional CSS class for this button
72
100
  */
@@ -81,6 +109,28 @@ export interface ButtonGroupConfig {
81
109
  * Array of button configurations
82
110
  */
83
111
  buttons?: ButtonGroupItemConfig[];
112
+ /** "standard" (default) or "connected" */
113
+ kind?: ButtonGroupKind;
114
+ /** "none" (default): plain actions. "single" or "multi": toggle buttons. */
115
+ selection?: ButtonGroupSelection;
116
+ /** With single or multi selection: the last selected button cannot be deselected */
117
+ required?: boolean;
118
+ /** Corner style: round (default) or square */
119
+ shape?: ButtonGroupShape;
120
+ /**
121
+ * Standard groups: share of its width a pressed button gains while its
122
+ * neighbours give up the difference (M3: 0.15). 0 disables the motion.
123
+ * @default 0.15
124
+ */
125
+ expandedRatio?: number;
126
+ /** Material size token: xs, s (default), m, l, xl */
127
+ size?: ButtonGroupSize;
128
+ /**
129
+ * "always" (default): buttons show icon and text. "selected": buttons with
130
+ * an icon and a text show the text only while selected; the selected button
131
+ * widens to reveal it (M3 Expressive connected groups).
132
+ */
133
+ labels?: ButtonGroupLabels;
84
134
  /**
85
135
  * Visual variant applied to all buttons in the group
86
136
  * @default 'outlined'
@@ -144,7 +194,10 @@ export interface ButtonGroupConfig {
144
194
  * Event handlers for button group events
145
195
  */
146
196
  on?: {
147
- [key in ButtonGroupEventType]?: (event: ButtonGroupEvent) => void;
197
+ click?: (event: ButtonGroupEvent) => void;
198
+ focus?: (event: ButtonGroupEvent) => void;
199
+ blur?: (event: ButtonGroupEvent) => void;
200
+ change?: (event: ButtonGroupChangeEvent) => void;
148
201
  };
149
202
  }
150
203
  /**
@@ -223,20 +276,31 @@ export interface ButtonGroupComponent {
223
276
  * @returns The ButtonGroupComponent for chaining
224
277
  */
225
278
  disableButton: (index: number) => ButtonGroupComponent;
279
+ /** Selection (groups with selection "single" or "multi") */
280
+ getSelected: () => string[];
281
+ isSelected: (value: string) => boolean;
282
+ select: (value: string) => ButtonGroupComponent;
283
+ deselect: (value: string) => ButtonGroupComponent;
284
+ toggle: (value: string) => ButtonGroupComponent;
285
+ getKind: () => ButtonGroupKind;
286
+ getSelection: () => ButtonGroupSelection;
226
287
  /**
227
288
  * Adds an event listener to the button group
228
289
  * @param event - Event name
229
290
  * @param handler - Event handler function
230
291
  * @returns The ButtonGroupComponent for chaining
231
292
  */
232
- on: (event: ButtonGroupEventType, handler: (event: ButtonGroupEvent) => void) => ButtonGroupComponent;
293
+ on: {
294
+ (event: "change", handler: (event: ButtonGroupChangeEvent) => void): ButtonGroupComponent;
295
+ (event: "click" | "focus" | "blur", handler: (event: ButtonGroupEvent) => void): ButtonGroupComponent;
296
+ };
233
297
  /**
234
298
  * Removes an event listener from the button group
235
299
  * @param event - Event name
236
300
  * @param handler - Event handler function
237
301
  * @returns The ButtonGroupComponent for chaining
238
302
  */
239
- off: (event: ButtonGroupEventType, handler: (event: ButtonGroupEvent) => void) => ButtonGroupComponent;
303
+ off: (event: ButtonGroupEventType, handler: (event: ButtonGroupEvent | ButtonGroupChangeEvent) => void) => ButtonGroupComponent;
240
304
  /**
241
305
  * Destroys the component and cleans up resources
242
306
  */
@@ -1,37 +1,18 @@
1
- import { CarouselComponent, CarouselSlide } from "./types";
2
- interface ApiOptions {
3
- slides: {
4
- addSlide: (slide: CarouselSlide, index?: number) => void;
5
- removeSlide: (index: number) => void;
6
- updateSlide: (index: number, slide: CarouselSlide) => void;
7
- getCount: () => number;
8
- getElements: () => HTMLElement[];
9
- };
10
- lifecycle: {
11
- destroy: () => void;
12
- };
13
- }
14
- interface ComponentWithElements {
1
+ import { CarouselComponent, CarouselVariant, SlidesAPI } from "./types";
2
+ interface ApiComponent {
15
3
  element: HTMLElement;
4
+ slides: SlidesAPI;
16
5
  getClass: (name: string) => string;
17
6
  getCurrentSlide: () => number;
18
- goTo: (index: number) => void;
7
+ getVariant: () => CarouselVariant;
19
8
  next: () => void;
20
9
  prev: () => void;
21
- enableLoop: () => void;
22
- disableLoop: () => void;
23
- setBorderRadius?: (radius: number) => void;
24
- setGap?: (gap: number) => void;
25
- on?: (event: string, handler: Function) => void;
26
- off?: (event: string, handler: Function) => void;
27
- addClass?: (...classes: string[]) => void;
28
- slideData?: CarouselSlide[];
10
+ goTo: (index: number) => void;
11
+ lifecycle?: {
12
+ destroy: () => void;
13
+ };
14
+ on?: (event: string, handler: Function) => unknown;
15
+ off?: (event: string, handler: Function) => unknown;
29
16
  }
30
- /**
31
- * Enhances a carousel component with API methods
32
- * @param {ApiOptions} options - API configuration options
33
- * @returns {Function} Higher-order function that adds API methods to component
34
- * @internal This is an internal utility for the Carousel component
35
- */
36
- export declare const withAPI: (options: ApiOptions) => (component: ComponentWithElements) => CarouselComponent;
17
+ export declare const withAPI: () => (component: ApiComponent) => CarouselComponent;
37
18
  export {};
@@ -0,0 +1,23 @@
1
+ export interface Arrangement {
2
+ priority: number;
3
+ smallSize: number;
4
+ smallCount: number;
5
+ mediumSize: number;
6
+ mediumCount: number;
7
+ largeSize: number;
8
+ largeCount: number;
9
+ }
10
+ export declare const itemCount: (a: Arrangement) => number;
11
+ export interface ArrangementOptions {
12
+ availableSpace: number;
13
+ gap: number;
14
+ targetSmallSize: number;
15
+ minSmallSize: number;
16
+ maxSmallSize: number;
17
+ smallCounts: number[];
18
+ targetMediumSize: number;
19
+ mediumCounts: number[];
20
+ targetLargeSize: number;
21
+ largeCounts: number[];
22
+ }
23
+ export declare const findLowestCostArrangement: (o: ArrangementOptions) => Arrangement | null;
@@ -1,75 +1,25 @@
1
- /**
2
- * Creates carousels with different layouts based on Material Design 3 guidelines.
3
- *
4
- * This module implements a carousel component that supports four layout types:
5
- * - Multi-browse: For browsing many visual items at once (photos, feeds)
6
- * - Uncontained: For customized or text-heavy carousels (traditional)
7
- * - Hero: For spotlighting large visual items (featured content)
8
- * - Full-screen: For immersive vertical-scrolling experiences
9
- *
10
- * Each layout is optimized for different content types and presentation needs,
11
- * following the Material Design 3 component guidelines.
12
- *
13
- * @module components/carousel
14
- * @category Components
15
- */
16
1
  import { CarouselConfig, CarouselComponent } from "./types";
17
2
  /**
18
- * Creates a new carousel component with the specified configuration.
19
- *
20
- * The carousel supports different layout types for various content
21
- * presentation needs, from image galleries to full-screen experiences.
22
- * It handles gesture interactions, keyboard navigation, and responsive
23
- * behavior following Material Design 3 guidelines.
3
+ * Creates a Material 3 carousel.
24
4
  *
25
- * @param {CarouselConfig} config - Configuration options for the carousel
26
- * @returns {CarouselComponent} A fully configured carousel component instance
27
- * @throws {Error} Throws an error if carousel creation fails
28
- *
29
- * @category Components
5
+ * Items are laid out by a keyline strategy per layout (multi-browse,
6
+ * uncontained, hero, centred hero, full-screen) and scrolled natively;
7
+ * they change size as they move through the layout and snap into place.
30
8
  *
31
9
  * @example
32
- * // Create a multi-browse carousel for a photo gallery
33
- * const photoGallery = createCarousel({
34
- * layout: 'multi-browse',
35
- * scrollBehavior: 'snap',
10
+ * ```ts
11
+ * const carousel = createCarousel({
12
+ * variant: 'hero',
13
+ * itemWidth: 360,
36
14
  * slides: [
37
- * { image: 'image1.jpg', title: 'Recent highlights', accent: '#3C4043' },
38
- * { image: 'image2.jpg', title: 'La Familia', accent: '#7E5260' }
15
+ * { image: 'a.jpg', title: 'Alpha' },
16
+ * { image: 'b.jpg', title: 'Beta' },
39
17
  * ],
40
- * showAllLink: true
41
- * });
42
- *
43
- * document.getElementById('gallery-container').appendChild(photoGallery.element);
44
- *
45
- * @example
46
- * // Create a hero carousel for featured content
47
- * const featuredContent = createCarousel({
48
- * layout: 'hero',
49
- * centered: true,
50
- * gap: 16,
51
- * slides: [
52
- * { image: 'hero1.jpg', title: 'Featured Story', buttonText: 'Read More' },
53
- * { image: 'hero2.jpg', title: 'Special Offer', buttonText: 'Shop Now' }
54
- * ]
55
- * });
56
- *
57
- * // Listen for slide changes
58
- * featuredContent.on('slide-changed', (index) => {
59
- * console.log(`Now showing featured item ${index}`);
60
18
  * });
19
+ * carousel.on('change', ({ index }) => console.log(index));
20
+ * ```
61
21
  *
62
- * @example
63
- * // Create a full-screen immersive carousel
64
- * const storyViewer = createCarousel({
65
- * layout: 'full-screen',
66
- * loop: false,
67
- * transition: 'fade',
68
- * slides: [
69
- * { image: 'story1.jpg', description: 'Chapter 1' },
70
- * { image: 'story2.jpg', description: 'Chapter 2' }
71
- * ]
72
- * });
22
+ * @category Components
73
23
  */
74
24
  export declare const createCarousel: (config?: CarouselConfig) => CarouselComponent;
75
25
  export default createCarousel;
@@ -1,19 +1,8 @@
1
1
  import { CarouselConfig } from "./types";
2
- /**
3
- * Default configuration for the Carousel component
4
- */
5
2
  export declare const defaultConfig: CarouselConfig;
6
- /**
7
- * Creates the base configuration for Carousel component
8
- * @param {CarouselConfig} config - User provided configuration
9
- * @returns {CarouselConfig} Complete configuration with defaults applied
10
- */
3
+ /** Layout-dependent defaults: full-screen has no padding and 16dp between items; uncontained scrolls freely */
4
+ export declare const resolveLayoutDefaults: (config: CarouselConfig) => Required<Pick<CarouselConfig, "variant" | "gap" | "padding" | "snap">>;
11
5
  export declare const createBaseConfig: (config?: CarouselConfig) => CarouselConfig;
12
- /**
13
- * Generates element configuration for the Carousel component
14
- * @param {CarouselConfig} config - Carousel configuration
15
- * @returns {Object} Element configuration object for withElement
16
- */
17
6
  export declare const getElementConfig: (config: CarouselConfig) => {
18
7
  tag: string;
19
8
  componentName: string;
@@ -36,21 +25,3 @@ export declare const getElementConfig: (config: CarouselConfig) => {
36
25
  forwardEvents: Record<string, boolean | ((component: any, event: Event) => boolean)>;
37
26
  interactive: boolean;
38
27
  };
39
- /**
40
- * Creates API configuration for the Carousel component
41
- * @param {Object} comp - Component with slides and lifecycle features
42
- * @returns {Object} API configuration object
43
- */
44
- export declare const getApiConfig: (comp: any) => {
45
- slides: {
46
- addSlide: any;
47
- removeSlide: any;
48
- updateSlide: any;
49
- getCount: any;
50
- getElements: any;
51
- };
52
- lifecycle: {
53
- destroy: any;
54
- };
55
- };
56
- export default defaultConfig;