mtrl 0.8.0-next.31 → 0.8.0-next.33

package/dist/components/index.d.ts

@@ -10,6 +10,7 @@
 export { default as createBadge } from "./badge";
 export { default as createBottomAppBar } from "./bottom-app-bar";
 export { default as createBottomSheet } from "./bottom-sheet";
+export { default as createSideSheet } from "./side-sheet";
 export { default as createButton } from "./button";
 export { default as createButtonGroup } from "./button-group";
 export { default as createCard } from "./card";
@@ -51,6 +52,7 @@ export { createCardContent, createCardHeader, createCardActions, createCardMedia
 export type { BadgeConfig, BadgeComponent } from "./badge/types";
 export type { BottomAppBarConfig, BottomAppBar } from "./bottom-app-bar/types";
 export type { BottomSheetConfig, BottomSheetComponent, BottomSheetVariant, BottomSheetState, BottomSheetStateEvent, BottomSheetEventHandlers, } from "./bottom-sheet/types";
+export type { SideSheetConfig, SideSheetComponent, SideSheetVariant, SideSheetPosition, SideSheetEventHandlers, } from "./side-sheet/types";
 export type { ButtonConfig, ButtonComponent, ButtonVariant, } from "./button/types";
 export type { ButtonGroupConfig, ButtonGroupComponent, ButtonGroupItemConfig, ButtonGroupEvent, ButtonGroupEventType, ButtonGroupVariant, ButtonGroupOrientation, ButtonGroupDensity, } from "./button-group/types";
 export type { CardSchema } from "./card/types";

package/dist/components/sheet/sheet.d.ts

@@ -1,6 +1,18 @@
 import { SheetConfig } from "./types";
 /**
  * Creates a new Sheet component
+ *
+ * @deprecated Since 0.8.0. Use {@link createBottomSheet} for a sheet anchored
+ * to the bottom edge, or {@link createSideSheet} for one docked to a vertical
+ * edge. Those follow the M3 bottom sheet and side sheet specifications, which
+ * this component predates and does not match.
+ *
+ * This component is also broken: `open()`, `close()` and the drag gestures
+ * call `component.events.emit(...)`, but it composes the event feature that
+ * provides `emit` directly and no `events` object, so every one of them
+ * throws. Its scrim is never inserted into the page either. It is kept only so
+ * that existing imports keep resolving, and it will be removed.
+ *
  * @param {SheetConfig} config - Sheet configuration object
  * @returns {SheetComponent} Sheet component instance
  */

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

@@ -24,6 +24,10 @@ export declare const SHEET_EVENTS: {
     readonly DRAG_START: "dragstart";
     readonly DRAG_END: "dragend";
 };
+/**
+ * @deprecated Since 0.8.0. Use BottomSheetConfig or SideSheetConfig.
+ * The sheet component this belongs to does not open: see createSheet.
+ */
 /**
  * Configuration interface for the Sheet component
  * @category Components
@@ -146,6 +150,10 @@ export interface TitleAPI {
      */
     getElement: () => HTMLElement | null;
 }
+/**
+ * @deprecated Since 0.8.0. Use BottomSheetComponent or SideSheetComponent.
+ * The sheet component this belongs to does not open: see createSheet.
+ */
 /**
  * Sheet component interface
  * @category Components

package/dist/components/side-sheet/api.d.ts

@@ -0,0 +1,33 @@
+import { SideSheetComponent, SideSheetEventHandlers } from "./types";
+interface ApiOptions {
+    state: {
+        open: () => void;
+        close: () => void;
+        toggle: () => void;
+        isOpen: () => boolean;
+        release: () => void;
+    };
+    structure: {
+        setContent: (content: string | HTMLElement) => void;
+        setTitle: (title: string) => void;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+}
+interface BaseComponent {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    on: (event: string, handler: (...args: never[]) => void) => unknown;
+    off: (event: string, handler: (...args: never[]) => void) => unknown;
+}
+/**
+ * The public surface. Every method is backed by a feature; none is declared
+ * and left unwired.
+ */
+export declare const withAPI: ({ state, structure, lifecycle }: ApiOptions) => <C extends BaseComponent>(component: C) => SideSheetComponent;
+/** Registers the handlers given at creation */
+export declare const applyEventHandlers: (component: {
+    on: (event: string, handler: (...args: never[]) => void) => unknown;
+}, handlers?: SideSheetEventHandlers) => void;
+export {};

package/dist/components/side-sheet/config.d.ts

@@ -0,0 +1,34 @@
+import { SideSheetConfig } from "./types";
+/**
+ * What the component applies when the caller says nothing.
+ */
+export declare const defaultConfig: Partial<SideSheetConfig>;
+/**
+ * Merges the caller's configuration over the defaults.
+ */
+export declare const createBaseConfig: (config?: SideSheetConfig) => SideSheetConfig;
+/**
+ * The root element: a fixed layer holding the scrim and the sheet itself.
+ */
+export declare const getElementConfig: (config: SideSheetConfig) => {
+    tag: string;
+    componentName: string;
+    attributes: Record<string, any>;
+    className: string[];
+    rawClass: string | string[];
+    id: string;
+    name: string;
+    title: string;
+    tabIndex: number;
+    style: string | Partial<CSSStyleDeclaration>;
+    data: Record<string, string>;
+    role: string;
+    ariaLabel: string;
+    ariaDescribedBy: string;
+    ariaLabelledBy: string;
+    ariaHidden: boolean;
+    html: string;
+    text: string;
+    forwardEvents: Record<string, boolean | ((component: any, event: Event) => boolean)>;
+    interactive: boolean;
+};

package/dist/components/side-sheet/constants.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Side sheet variants.
+ *
+ * A standard sheet is docked: it sits in the layout beside the page and leaves
+ * it usable. A modal sheet floats over the page behind a scrim and takes focus.
+ * They differ in colour as well as behaviour, which is why the variant is not
+ * only a class (m3.material.io/components/side-sheets).
+ */
+export declare const SIDE_SHEET_VARIANTS: {
+    readonly STANDARD: "standard";
+    readonly MODAL: "modal";
+};
+/**
+ * Which edge the sheet is docked to.
+ *
+ * These are logical, not physical: `end` is the right edge in a left-to-right
+ * document and the left edge in a right-to-left one, so a sheet does not need
+ * reconfiguring per language.
+ */
+export declare const SIDE_SHEET_POSITIONS: {
+    readonly START: "start";
+    readonly END: "end";
+};
+/**
+ * Defaults, from the M3 side sheet specs and the Android implementation.
+ */
+export declare const SIDE_SHEET_DEFAULTS: {
+    readonly VARIANT: "modal";
+    /** Side sheets dock to the trailing edge unless told otherwise */
+    readonly POSITION: "end";
+    /** The width the Android implementation uses for a standard sheet */
+    readonly WIDTH: 256;
+    /** m3.material.io side sheet specs, container maximum width */
+    readonly MAX_WIDTH: 400;
+    /** A modal sheet offers a way out of itself */
+    readonly CLOSE_BUTTON: true;
+    readonly CLOSE_ON_SCRIM_CLICK: true;
+    readonly CLOSE_ON_ESCAPE: true;
+};
+/**
+ * Class names, without the prefix. `getClass` adds it.
+ */
+export declare const SIDE_SHEET_CLASSES: {
+    readonly ROOT: "side-sheet";
+    readonly SCRIM: "side-sheet-scrim";
+    readonly CONTAINER: "side-sheet-container";
+    readonly HEADER: "side-sheet-header";
+    readonly TITLE: "side-sheet-title";
+    readonly CLOSE: "side-sheet-close";
+    readonly DIVIDER: "side-sheet-divider";
+    readonly CONTENT: "side-sheet-content";
+    readonly ACTIONS: "side-sheet-actions";
+};
+/**
+ * Events the sheet emits.
+ */
+export declare const SIDE_SHEET_EVENTS: {
+    readonly OPEN: "open";
+    readonly CLOSE: "close";
+};

package/dist/components/side-sheet/features/index.d.ts

@@ -0,0 +1,2 @@
+export { withStructure } from "./structure";
+export { withState } from "./state";

package/dist/components/side-sheet/features/state.d.ts

@@ -0,0 +1,28 @@
+import { SideSheetConfig } from "../types";
+interface StateComponent {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => unknown;
+    structure: {
+        scrim: HTMLElement | null;
+        container: HTMLElement;
+        closeButton: HTMLButtonElement | null;
+    };
+}
+/**
+ * Opening and closing, and everything that closes it.
+ *
+ * Events go through `component.emit`, which is what the composed events
+ * enhancer provides.
+ */
+export declare const withState: (config: SideSheetConfig) => <C extends StateComponent>(component: C) => C & {
+    state: {
+        open: () => void;
+        close: () => void;
+        toggle: () => void;
+        isOpen: () => boolean;
+        /** Releases the listeners this feature put on the document */
+        release: () => void;
+    };
+};
+export {};

package/dist/components/side-sheet/features/structure.d.ts

@@ -0,0 +1,21 @@
+import { SideSheetConfig } from "../types";
+/**
+ * Builds the parts of the sheet and puts the whole thing on the page.
+ *
+ * As with the bottom sheet, the root element holds both the scrim and the
+ * container, so neither depends on a parent that does not exist yet.
+ */
+export declare const withStructure: (config: SideSheetConfig) => <C extends {
+    element: HTMLElement;
+    getClass: (n: string) => string;
+}>(component: C) => C & {
+    structure: {
+        scrim: HTMLElement;
+        container: HTMLDivElement;
+        title: HTMLElement;
+        closeButton: HTMLButtonElement;
+        content: HTMLDivElement;
+        setContent(next: string | HTMLElement): void;
+        setTitle(next: string): void;
+    };
+};

package/dist/components/side-sheet/index.d.ts

@@ -0,0 +1,2 @@
+export { default as createSideSheet, default } from "./side-sheet";
+export type { SideSheetConfig, SideSheetComponent, SideSheetVariant, SideSheetPosition, SideSheetEventHandlers, } from "./types";

package/dist/components/side-sheet/side-sheet.d.ts

@@ -0,0 +1,24 @@
+import { SideSheetConfig, SideSheetComponent } from "./types";
+/**
+ * Creates a side sheet: a surface docked to a vertical edge, holding content
+ * that supports the page rather than replacing it.
+ *
+ * A standard sheet sits beside the page and leaves it usable. A modal sheet
+ * floats over it behind a scrim and takes focus.
+ *
+ * @param {SideSheetConfig} config - Side sheet configuration
+ * @returns {SideSheetComponent} Side sheet instance
+ *
+ * @example
+ * ```ts
+ * const filters = createSideSheet({
+ *   title: 'Filters',
+ *   content: '<p>Narrow the results.</p>',
+ *   on: { close: () => applyFilters() }
+ * });
+ *
+ * filters.open();
+ * ```
+ */
+declare const createSideSheet: (config?: SideSheetConfig) => SideSheetComponent;
+export default createSideSheet;

package/dist/components/side-sheet/types.d.ts

@@ -0,0 +1,102 @@
+import { SIDE_SHEET_VARIANTS, SIDE_SHEET_POSITIONS } from "./constants";
+/** Docked or floating over a scrim */
+export type SideSheetVariant = (typeof SIDE_SHEET_VARIANTS)[keyof typeof SIDE_SHEET_VARIANTS];
+/** Which edge it docks to, in logical terms */
+export type SideSheetPosition = (typeof SIDE_SHEET_POSITIONS)[keyof typeof SIDE_SHEET_POSITIONS];
+/** Handlers accepted at creation, one per event name */
+export interface SideSheetEventHandlers {
+    open?: () => void;
+    close?: () => void;
+}
+/**
+ * Configuration for the side sheet.
+ *
+ * @category Components
+ */
+export interface SideSheetConfig {
+    /**
+     * Standard sheets dock beside the page and leave it usable; modal sheets
+     * float over it behind a scrim and take focus.
+     * @default 'modal'
+     */
+    variant?: SideSheetVariant;
+    /**
+     * Which edge to dock to. Logical, so `end` follows the writing direction.
+     * @default 'end'
+     */
+    position?: SideSheetPosition;
+    /**
+     * Headline in the header. Also names the sheet for assistive technology,
+     * through `aria-labelledby`.
+     */
+    title?: string;
+    /** Body of the sheet, as markup or an element */
+    content?: string | HTMLElement;
+    /**
+     * Width in pixels. Capped by `maxWidth`.
+     * @default 256
+     */
+    width?: number;
+    /**
+     * The sheet never grows past this, so it does not take over a wide window.
+     * @default 400
+     */
+    maxWidth?: number;
+    /**
+     * Whether the header carries a close button.
+     * @default true
+     */
+    closeButton?: boolean;
+    /**
+     * Whether a click on the scrim closes a modal sheet. Standard sheets have no
+     * scrim, so this does nothing for them.
+     * @default true
+     */
+    closeOnScrimClick?: boolean;
+    /**
+     * Whether Escape closes it.
+     * @default true
+     */
+    closeOnEscape?: boolean;
+    /** Whether the sheet starts open */
+    open?: boolean;
+    /** Where to mount the sheet. Defaults to `document.body` */
+    container?: HTMLElement;
+    /** Handlers registered at creation, equivalent to calling `on` for each */
+    on?: SideSheetEventHandlers;
+    /** Extra classes for the root element */
+    class?: string;
+    /** @internal */
+    prefix?: string;
+    /** @internal */
+    componentName?: string;
+}
+/**
+ * A side sheet instance.
+ *
+ * @category Components
+ */
+export interface SideSheetComponent {
+    /** The root element, which holds the scrim and the container */
+    element: HTMLElement;
+    /** Opens the sheet */
+    open: () => SideSheetComponent;
+    /** Closes the sheet */
+    close: () => SideSheetComponent;
+    /** Opens it if closed, closes it if open */
+    toggle: () => SideSheetComponent;
+    /** Whether the sheet is showing */
+    isOpen: () => boolean;
+    /** Replaces the body */
+    setContent: (content: string | HTMLElement) => SideSheetComponent;
+    /** Replaces the headline */
+    setTitle: (title: string) => SideSheetComponent;
+    /** Adds an event listener */
+    on: <T extends keyof SideSheetEventHandlers>(event: T, handler: NonNullable<SideSheetEventHandlers[T]>) => SideSheetComponent;
+    /** Removes an event listener */
+    off: <T extends keyof SideSheetEventHandlers>(event: T, handler: NonNullable<SideSheetEventHandlers[T]>) => SideSheetComponent;
+    /** Removes the sheet from the page and releases its listeners */
+    destroy: () => void;
+    /** Prefixes a class name, for styling hooks */
+    getClass: (name: string) => string;
+}