/** * @license * Copyright 2026 Aglyn LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * How a lightbox looks and closes (AGL-3717), as plain data. * * ## Why this is its own module * * `lightbox-dialog.tsx` names `@mui/material/Dialog`, and the Dialog stack is * kept off every first paint (AGL-1290): an element reaches the dialog through * `lazy(() => import())` only once a visitor asks for it. What an element has * to know BEFORE that — which props are the lightbox's, so it does not spread * them onto its own DOM, and what each one is called in a props panel — lives * here, with no React and no MUI, so reading it costs a page nothing. * * The field list is generic on purpose: it says what each setting is and what * kind of control edits it, never how a particular editor draws that control. * Every element that opens a lightbox maps it onto its own schema, so the * Image, the Image List, the Video and the Lightbox container all offer the * same settings under the same names, and a reusable component's property can * be bound to any of them the same way. */ /** What draws the close control. */ export declare const LIGHTBOX_CLOSE_STYLES: readonly ["icon", "filled", "text"]; export type LightboxCloseStyle = (typeof LIGHTBOX_CLOSE_STYLES)[number]; /** Where the close control sits: in the frame's top corner, or the screen's. */ export declare const LIGHTBOX_CLOSE_POSITIONS: readonly ["inside-end", "inside-start", "outside-end"]; export type LightboxClosePosition = (typeof LIGHTBOX_CLOSE_POSITIONS)[number]; /** Where a picture's caption goes: under it, over its foot, or nowhere. */ export declare const LIGHTBOX_CAPTION_PLACEMENTS: readonly ["below", "overlay", "hidden"]; export type LightboxCaptionPlacement = (typeof LIGHTBOX_CAPTION_PLACEMENTS)[number]; /** How the lightbox arrives. A visitor who asks for reduced motion gets `none`. */ export declare const LIGHTBOX_TRANSITIONS: readonly ["fade", "zoom", "none"]; export type LightboxTransition = (typeof LIGHTBOX_TRANSITIONS)[number]; /** * The resolved settings. Every look field is optional and absent means "the * element's own default", which is what keeps an element that existed before * these settings — the Video — rendering exactly as it did. The two closing * rules are always resolved, because a dialog has to decide them. */ export interface LightboxAppearance { backdropColor?: string; /** 0–100. */ backdropOpacity?: number; /** Pixels of blur behind the backdrop. */ backdropBlur?: number; /** Any CSS length. */ maxWidth?: string; maxHeight?: string; padding?: string; /** Corner radius of the frame, in pixels. */ radius?: number; closeStyle?: LightboxCloseStyle; closePosition?: LightboxClosePosition; captionPlacement?: LightboxCaptionPlacement; transition?: LightboxTransition; closeOnBackdrop: boolean; closeOnEscape: boolean; } /** * The prop each setting is stored under on an element. Persisted in screen * documents; never rename a value. */ export declare const LIGHTBOX_APPEARANCE_PROPS: { readonly backdropColor: "lightboxBackdropColor"; readonly backdropOpacity: "lightboxBackdropOpacity"; readonly backdropBlur: "lightboxBackdropBlur"; readonly maxWidth: "lightboxMaxWidth"; readonly maxHeight: "lightboxMaxHeight"; readonly padding: "lightboxPadding"; readonly radius: "lightboxRadius"; readonly closeStyle: "lightboxCloseStyle"; readonly closePosition: "lightboxClosePosition"; readonly captionPlacement: "lightboxCaptionPlacement"; readonly transition: "lightboxTransition"; readonly closeOnBackdrop: "lightboxCloseOnBackdrop"; readonly closeOnEscape: "lightboxCloseOnEscape"; }; export type LightboxAppearancePropName = (typeof LIGHTBOX_APPEARANCE_PROPS)[keyof typeof LIGHTBOX_APPEARANCE_PROPS]; /** Every appearance prop name, for an element to keep off its own DOM. */ export declare const LIGHTBOX_APPEARANCE_PROP_NAMES: readonly LightboxAppearancePropName[]; /** The props an element carries for its lightbox's look, as stored. */ export type LightboxAppearanceProps = Partial>; /** The kind of control a setting is edited with. */ export type LightboxFieldKind = 'color' | 'number' | 'dimension' | 'select' | 'switch'; export interface LightboxFieldDescriptor { name: LightboxAppearancePropName; label: string; description: string; kind: LightboxFieldKind; options?: ReadonlyArray<{ value: string; label: string; }>; } /** * The settings, in the order a props panel lists them. Each select's first * option is the default and a real value, so an author can always move back * to it (a `''` option could not persist, AGL-1191). */ export declare const LIGHTBOX_APPEARANCE_FIELDS: readonly LightboxFieldDescriptor[]; /** * Reads the settings off an element's props. Anything unreadable is treated * as unset rather than thrown on, because a stored document can hold any * value and a lightbox that refuses to open over a bad radius is worse than * one with square corners. */ export declare function readLightboxAppearance(props: Readonly> | null | undefined): LightboxAppearance; /** * Splits an element's props into its lightbox settings and everything else, * so the rest can be spread onto the element's DOM without a dozen unknown * attributes riding along. */ export declare function splitLightboxAppearanceProps(props: T): { appearance: LightboxAppearance; rest: Omit; }; /** * The backdrop's paint: the color at the opacity asked for. A hex color is * written as `rgba()`; any other color — a name, an `rgb()`, a theme variable * — is mixed with transparency, which every browser that renders the dialog * supports. `undefined` when neither is set, so the theme's backdrop stays. */ export declare function lightboxBackdropBackground(appearance: Pick): string | undefined;