@aglyn/shared-ui-jsx 1.0.0-beta.235 → 1.0.0-beta.237

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/shared-ui-jsx",
-  "version": "1.0.0-beta.235",
+  "version": "1.0.0-beta.237",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,10 +25,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-mdi": "1.0.0-beta.235",
-    "@aglyn/shared-ui-theme": "1.0.0-beta.235",
-    "@aglyn/shared-util-tools": "1.0.0-beta.235",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.235",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.237",
+    "@aglyn/shared-ui-theme": "1.0.0-beta.237",
+    "@aglyn/shared-util-tools": "1.0.0-beta.237",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.237",
     "@mdi/js": "^7.4.47",
     "@swc/helpers": "0.5.23",
     "change-case": "^5.4.4",

package/src/lib/components/lightbox/lightbox-appearance.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @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<Record<LightboxAppearancePropName, string | number | boolean | null>>;
+/** 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<Record<string, unknown>> | 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<T extends object>(props: T): {
+    appearance: LightboxAppearance;
+    rest: Omit<T, LightboxAppearancePropName>;
+};
+/**
+ * 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<LightboxAppearance, 'backdropColor' | 'backdropOpacity'>): string | undefined;

package/src/lib/components/lightbox/lightbox-appearance.js

@@ -0,0 +1,308 @@
+/**
+ * @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 const LIGHTBOX_CLOSE_STYLES = [
+    'icon',
+    'filled',
+    'text'
+];
+/** Where the close control sits: in the frame's top corner, or the screen's. */ export const LIGHTBOX_CLOSE_POSITIONS = [
+    'inside-end',
+    'inside-start',
+    'outside-end'
+];
+/** Where a picture's caption goes: under it, over its foot, or nowhere. */ export const LIGHTBOX_CAPTION_PLACEMENTS = [
+    'below',
+    'overlay',
+    'hidden'
+];
+/** How the lightbox arrives. A visitor who asks for reduced motion gets `none`. */ export const LIGHTBOX_TRANSITIONS = [
+    'fade',
+    'zoom',
+    'none'
+];
+/**
+ * The prop each setting is stored under on an element. Persisted in screen
+ * documents; never rename a value.
+ */ export const LIGHTBOX_APPEARANCE_PROPS = {
+    backdropColor: 'lightboxBackdropColor',
+    backdropOpacity: 'lightboxBackdropOpacity',
+    backdropBlur: 'lightboxBackdropBlur',
+    maxWidth: 'lightboxMaxWidth',
+    maxHeight: 'lightboxMaxHeight',
+    padding: 'lightboxPadding',
+    radius: 'lightboxRadius',
+    closeStyle: 'lightboxCloseStyle',
+    closePosition: 'lightboxClosePosition',
+    captionPlacement: 'lightboxCaptionPlacement',
+    transition: 'lightboxTransition',
+    closeOnBackdrop: 'lightboxCloseOnBackdrop',
+    closeOnEscape: 'lightboxCloseOnEscape'
+};
+/** Every appearance prop name, for an element to keep off its own DOM. */ export const LIGHTBOX_APPEARANCE_PROP_NAMES = Object.values(LIGHTBOX_APPEARANCE_PROPS);
+/**
+ * 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 const LIGHTBOX_APPEARANCE_FIELDS = [
+    {
+        name: 'lightboxBackdropColor',
+        label: 'Lightbox backdrop color',
+        description: 'The color behind the lightbox. Leave empty for a dark backdrop.',
+        kind: 'color'
+    },
+    {
+        name: 'lightboxBackdropOpacity',
+        label: 'Lightbox backdrop opacity',
+        description: 'How solid the backdrop is, from 0 (clear) to 100 (solid).',
+        kind: 'number'
+    },
+    {
+        name: 'lightboxBackdropBlur',
+        label: 'Lightbox backdrop blur',
+        description: 'Blurs the page behind the lightbox, in pixels. 0 for none.',
+        kind: 'number'
+    },
+    {
+        name: 'lightboxMaxWidth',
+        label: 'Lightbox max width',
+        description: 'The widest the lightbox frame grows, e.g. 1200px or 90vw.',
+        kind: 'dimension'
+    },
+    {
+        name: 'lightboxMaxHeight',
+        label: 'Lightbox max height',
+        description: 'The tallest the lightbox frame grows, e.g. 90vh.',
+        kind: 'dimension'
+    },
+    {
+        name: 'lightboxPadding',
+        label: 'Lightbox padding',
+        description: 'Space between the frame edge and what it shows.',
+        kind: 'dimension'
+    },
+    {
+        name: 'lightboxRadius',
+        label: 'Lightbox corner radius',
+        description: 'Rounds the frame corners, in pixels.',
+        kind: 'number'
+    },
+    {
+        name: 'lightboxCloseStyle',
+        label: 'Lightbox close button',
+        description: 'How the close button looks.',
+        kind: 'select',
+        options: [
+            {
+                value: 'icon',
+                label: 'Icon (default)'
+            },
+            {
+                value: 'filled',
+                label: 'Icon on a circle'
+            },
+            {
+                value: 'text',
+                label: 'The word Close'
+            }
+        ]
+    },
+    {
+        name: 'lightboxClosePosition',
+        label: 'Lightbox close position',
+        description: 'Where the close button sits.',
+        kind: 'select',
+        options: [
+            {
+                value: 'inside-end',
+                label: 'Frame, top right (default)'
+            },
+            {
+                value: 'inside-start',
+                label: 'Frame, top left'
+            },
+            {
+                value: 'outside-end',
+                label: 'Screen, top right'
+            }
+        ]
+    },
+    {
+        name: 'lightboxCaptionPlacement',
+        label: 'Lightbox caption',
+        description: 'Where a picture caption shows in the lightbox.',
+        kind: 'select',
+        options: [
+            {
+                value: 'below',
+                label: 'Below the picture (default)'
+            },
+            {
+                value: 'overlay',
+                label: 'Over the picture'
+            },
+            {
+                value: 'hidden',
+                label: 'Hidden'
+            }
+        ]
+    },
+    {
+        name: 'lightboxTransition',
+        label: 'Lightbox transition',
+        description: 'How the lightbox opens. Visitors who ask for reduced motion always get none.',
+        kind: 'select',
+        options: [
+            {
+                value: 'fade',
+                label: 'Fade (default)'
+            },
+            {
+                value: 'zoom',
+                label: 'Zoom'
+            },
+            {
+                value: 'none',
+                label: 'None'
+            }
+        ]
+    },
+    {
+        name: 'lightboxCloseOnBackdrop',
+        label: 'Close on backdrop click',
+        description: 'Closes the lightbox when a visitor clicks outside it. On by default.',
+        kind: 'switch'
+    },
+    {
+        name: 'lightboxCloseOnEscape',
+        label: 'Close on Escape',
+        description: 'Closes the lightbox when a visitor presses Escape. On by default.',
+        kind: 'switch'
+    }
+];
+const text = (value)=>{
+    if (typeof value === 'number' && Number.isFinite(value)) return `${value}`;
+    if (typeof value !== 'string') return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+};
+const number = (value, min, max)=>{
+    if (value === null || value === undefined || value === '') return undefined;
+    const parsed = typeof value === 'number' ? value : Number(String(value).trim());
+    if (!Number.isFinite(parsed)) return undefined;
+    return Math.min(Math.max(parsed, min), max);
+};
+const oneOf = (value, allowed)=>typeof value === 'string' && allowed.includes(value) ? value : undefined;
+/**
+ * A yes/no that defaults to yes: only an explicit no turns it off. The
+ * strings are what a document, a reusable component's text substitution or
+ * an older editor may hold.
+ */ const onUnlessNo = (value)=>!(value === false || value === 'false' || value === 'no' || value === 0);
+/** A unitless length is pixels, as everywhere else on an element. */ const length = (value)=>{
+    const raw = text(value);
+    if (raw === undefined) return undefined;
+    return /^\d+(\.\d+)?$/.test(raw) ? `${raw}px` : raw;
+};
+/**
+ * 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 function readLightboxAppearance(props) {
+    const bag = props != null ? props : {};
+    const P = LIGHTBOX_APPEARANCE_PROPS;
+    const appearance = {
+        closeOnBackdrop: onUnlessNo(bag[P.closeOnBackdrop]),
+        closeOnEscape: onUnlessNo(bag[P.closeOnEscape])
+    };
+    const backdropColor = text(bag[P.backdropColor]);
+    if (backdropColor) appearance.backdropColor = backdropColor;
+    const backdropOpacity = number(bag[P.backdropOpacity], 0, 100);
+    if (backdropOpacity !== undefined) appearance.backdropOpacity = backdropOpacity;
+    const backdropBlur = number(bag[P.backdropBlur], 0, 64);
+    if (backdropBlur !== undefined) appearance.backdropBlur = backdropBlur;
+    const maxWidth = length(bag[P.maxWidth]);
+    if (maxWidth) appearance.maxWidth = maxWidth;
+    const maxHeight = length(bag[P.maxHeight]);
+    if (maxHeight) appearance.maxHeight = maxHeight;
+    const padding = length(bag[P.padding]);
+    if (padding) appearance.padding = padding;
+    const radius = number(bag[P.radius], 0, 999);
+    if (radius !== undefined) appearance.radius = radius;
+    const closeStyle = oneOf(bag[P.closeStyle], LIGHTBOX_CLOSE_STYLES);
+    if (closeStyle) appearance.closeStyle = closeStyle;
+    const closePosition = oneOf(bag[P.closePosition], LIGHTBOX_CLOSE_POSITIONS);
+    if (closePosition) appearance.closePosition = closePosition;
+    const captionPlacement = oneOf(bag[P.captionPlacement], LIGHTBOX_CAPTION_PLACEMENTS);
+    if (captionPlacement) appearance.captionPlacement = captionPlacement;
+    const transition = oneOf(bag[P.transition], LIGHTBOX_TRANSITIONS);
+    if (transition) appearance.transition = transition;
+    return appearance;
+}
+/**
+ * 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 function splitLightboxAppearanceProps(props) {
+    const rest = {};
+    const names = new Set(LIGHTBOX_APPEARANCE_PROP_NAMES);
+    for (const [key, value] of Object.entries(props)){
+        if (!names.has(key)) rest[key] = value;
+    }
+    return {
+        appearance: readLightboxAppearance(props),
+        rest: rest
+    };
+}
+/**
+ * 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 function lightboxBackdropBackground(appearance) {
+    const { backdropColor, backdropOpacity } = appearance;
+    if (!backdropColor && backdropOpacity === undefined) return undefined;
+    const color = backdropColor != null ? backdropColor : '#000000';
+    const opacity = backdropOpacity != null ? backdropOpacity : 80;
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color);
+    if (hex) {
+        const digits = hex[1].length === 3 ? hex[1].split('').map((digit)=>digit + digit).join('') : hex[1];
+        const red = parseInt(digits.slice(0, 2), 16);
+        const green = parseInt(digits.slice(2, 4), 16);
+        const blue = parseInt(digits.slice(4, 6), 16);
+        return `rgba(${red}, ${green}, ${blue}, ${opacity / 100})`;
+    }
+    return `color-mix(in srgb, ${color} ${opacity}%, transparent)`;
+}
+
+//# sourceMappingURL=lightbox-appearance.js.map

package/src/lib/components/lightbox/lightbox-appearance.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/shared/ui/jsx/src/lib/components/lightbox/lightbox-appearance.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * How a lightbox looks and closes (AGL-3717), as plain data.\n *\n * ## Why this is its own module\n *\n * `lightbox-dialog.tsx` names `@mui/material/Dialog`, and the Dialog stack is\n * kept off every first paint (AGL-1290): an element reaches the dialog through\n * `lazy(() => import())` only once a visitor asks for it. What an element has\n * to know BEFORE that — which props are the lightbox's, so it does not spread\n * them onto its own DOM, and what each one is called in a props panel — lives\n * here, with no React and no MUI, so reading it costs a page nothing.\n *\n * The field list is generic on purpose: it says what each setting is and what\n * kind of control edits it, never how a particular editor draws that control.\n * Every element that opens a lightbox maps it onto its own schema, so the\n * Image, the Image List, the Video and the Lightbox container all offer the\n * same settings under the same names, and a reusable component's property can\n * be bound to any of them the same way.\n */\n\n/** What draws the close control. */\nexport const LIGHTBOX_CLOSE_STYLES = ['icon', 'filled', 'text'] as const\nexport type LightboxCloseStyle = (typeof LIGHTBOX_CLOSE_STYLES)[number]\n\n/** Where the close control sits: in the frame's top corner, or the screen's. */\nexport const LIGHTBOX_CLOSE_POSITIONS = [\n  'inside-end',\n  'inside-start',\n  'outside-end',\n] as const\nexport type LightboxClosePosition = (typeof LIGHTBOX_CLOSE_POSITIONS)[number]\n\n/** Where a picture's caption goes: under it, over its foot, or nowhere. */\nexport const LIGHTBOX_CAPTION_PLACEMENTS = ['below', 'overlay', 'hidden'] as const\nexport type LightboxCaptionPlacement =\n  (typeof LIGHTBOX_CAPTION_PLACEMENTS)[number]\n\n/** How the lightbox arrives. A visitor who asks for reduced motion gets `none`. */\nexport const LIGHTBOX_TRANSITIONS = ['fade', 'zoom', 'none'] as const\nexport type LightboxTransition = (typeof LIGHTBOX_TRANSITIONS)[number]\n\n/**\n * The resolved settings. Every look field is optional and absent means \"the\n * element's own default\", which is what keeps an element that existed before\n * these settings — the Video — rendering exactly as it did. The two closing\n * rules are always resolved, because a dialog has to decide them.\n */\nexport interface LightboxAppearance {\n  backdropColor?: string\n  /** 0–100. */\n  backdropOpacity?: number\n  /** Pixels of blur behind the backdrop. */\n  backdropBlur?: number\n  /** Any CSS length. */\n  maxWidth?: string\n  maxHeight?: string\n  padding?: string\n  /** Corner radius of the frame, in pixels. */\n  radius?: number\n  closeStyle?: LightboxCloseStyle\n  closePosition?: LightboxClosePosition\n  captionPlacement?: LightboxCaptionPlacement\n  transition?: LightboxTransition\n  closeOnBackdrop: boolean\n  closeOnEscape: boolean\n}\n\n/**\n * The prop each setting is stored under on an element. Persisted in screen\n * documents; never rename a value.\n */\nexport const LIGHTBOX_APPEARANCE_PROPS = {\n  backdropColor: 'lightboxBackdropColor',\n  backdropOpacity: 'lightboxBackdropOpacity',\n  backdropBlur: 'lightboxBackdropBlur',\n  maxWidth: 'lightboxMaxWidth',\n  maxHeight: 'lightboxMaxHeight',\n  padding: 'lightboxPadding',\n  radius: 'lightboxRadius',\n  closeStyle: 'lightboxCloseStyle',\n  closePosition: 'lightboxClosePosition',\n  captionPlacement: 'lightboxCaptionPlacement',\n  transition: 'lightboxTransition',\n  closeOnBackdrop: 'lightboxCloseOnBackdrop',\n  closeOnEscape: 'lightboxCloseOnEscape',\n} as const satisfies Record<keyof LightboxAppearance, string>\n\nexport type LightboxAppearancePropName =\n  (typeof LIGHTBOX_APPEARANCE_PROPS)[keyof typeof LIGHTBOX_APPEARANCE_PROPS]\n\n/** Every appearance prop name, for an element to keep off its own DOM. */\nexport const LIGHTBOX_APPEARANCE_PROP_NAMES: readonly LightboxAppearancePropName[] =\n  Object.values(LIGHTBOX_APPEARANCE_PROPS)\n\n/** The props an element carries for its lightbox's look, as stored. */\nexport type LightboxAppearanceProps = Partial<\n  Record<LightboxAppearancePropName, string | number | boolean | null>\n>\n\n/** The kind of control a setting is edited with. */\nexport type LightboxFieldKind =\n  | 'color'\n  | 'number'\n  | 'dimension'\n  | 'select'\n  | 'switch'\n\nexport interface LightboxFieldDescriptor {\n  name: LightboxAppearancePropName\n  label: string\n  description: string\n  kind: LightboxFieldKind\n  options?: ReadonlyArray<{ value: string; label: string }>\n}\n\n/**\n * The settings, in the order a props panel lists them. Each select's first\n * option is the default and a real value, so an author can always move back\n * to it (a `''` option could not persist, AGL-1191).\n */\nexport const LIGHTBOX_APPEARANCE_FIELDS: readonly LightboxFieldDescriptor[] = [\n  {\n    name: 'lightboxBackdropColor',\n    label: 'Lightbox backdrop color',\n    description: 'The color behind the lightbox. Leave empty for a dark backdrop.',\n    kind: 'color',\n  },\n  {\n    name: 'lightboxBackdropOpacity',\n    label: 'Lightbox backdrop opacity',\n    description: 'How solid the backdrop is, from 0 (clear) to 100 (solid).',\n    kind: 'number',\n  },\n  {\n    name: 'lightboxBackdropBlur',\n    label: 'Lightbox backdrop blur',\n    description: 'Blurs the page behind the lightbox, in pixels. 0 for none.',\n    kind: 'number',\n  },\n  {\n    name: 'lightboxMaxWidth',\n    label: 'Lightbox max width',\n    description: 'The widest the lightbox frame grows, e.g. 1200px or 90vw.',\n    kind: 'dimension',\n  },\n  {\n    name: 'lightboxMaxHeight',\n    label: 'Lightbox max height',\n    description: 'The tallest the lightbox frame grows, e.g. 90vh.',\n    kind: 'dimension',\n  },\n  {\n    name: 'lightboxPadding',\n    label: 'Lightbox padding',\n    description: 'Space between the frame edge and what it shows.',\n    kind: 'dimension',\n  },\n  {\n    name: 'lightboxRadius',\n    label: 'Lightbox corner radius',\n    description: 'Rounds the frame corners, in pixels.',\n    kind: 'number',\n  },\n  {\n    name: 'lightboxCloseStyle',\n    label: 'Lightbox close button',\n    description: 'How the close button looks.',\n    kind: 'select',\n    options: [\n      { value: 'icon', label: 'Icon (default)' },\n      { value: 'filled', label: 'Icon on a circle' },\n      { value: 'text', label: 'The word Close' },\n    ],\n  },\n  {\n    name: 'lightboxClosePosition',\n    label: 'Lightbox close position',\n    description: 'Where the close button sits.',\n    kind: 'select',\n    options: [\n      { value: 'inside-end', label: 'Frame, top right (default)' },\n      { value: 'inside-start', label: 'Frame, top left' },\n      { value: 'outside-end', label: 'Screen, top right' },\n    ],\n  },\n  {\n    name: 'lightboxCaptionPlacement',\n    label: 'Lightbox caption',\n    description: 'Where a picture caption shows in the lightbox.',\n    kind: 'select',\n    options: [\n      { value: 'below', label: 'Below the picture (default)' },\n      { value: 'overlay', label: 'Over the picture' },\n      { value: 'hidden', label: 'Hidden' },\n    ],\n  },\n  {\n    name: 'lightboxTransition',\n    label: 'Lightbox transition',\n    description:\n      'How the lightbox opens. Visitors who ask for reduced motion always get none.',\n    kind: 'select',\n    options: [\n      { value: 'fade', label: 'Fade (default)' },\n      { value: 'zoom', label: 'Zoom' },\n      { value: 'none', label: 'None' },\n    ],\n  },\n  {\n    name: 'lightboxCloseOnBackdrop',\n    label: 'Close on backdrop click',\n    description: 'Closes the lightbox when a visitor clicks outside it. On by default.',\n    kind: 'switch',\n  },\n  {\n    name: 'lightboxCloseOnEscape',\n    label: 'Close on Escape',\n    description: 'Closes the lightbox when a visitor presses Escape. On by default.',\n    kind: 'switch',\n  },\n]\n\nconst text = (value: unknown): string | undefined => {\n  if (typeof value === 'number' && Number.isFinite(value)) return `${value}`\n  if (typeof value !== 'string') return undefined\n  const trimmed = value.trim()\n  return trimmed ? trimmed : undefined\n}\n\nconst number = (\n  value: unknown,\n  min: number,\n  max: number,\n): number | undefined => {\n  if (value === null || value === undefined || value === '') return undefined\n  const parsed = typeof value === 'number' ? value : Number(String(value).trim())\n  if (!Number.isFinite(parsed)) return undefined\n  return Math.min(Math.max(parsed, min), max)\n}\n\nconst oneOf = <T extends string>(\n  value: unknown,\n  allowed: readonly T[],\n): T | undefined =>\n  typeof value === 'string' && (allowed as readonly string[]).includes(value)\n    ? (value as T)\n    : undefined\n\n/**\n * A yes/no that defaults to yes: only an explicit no turns it off. The\n * strings are what a document, a reusable component's text substitution or\n * an older editor may hold.\n */\nconst onUnlessNo = (value: unknown): boolean =>\n  !(value === false || value === 'false' || value === 'no' || value === 0)\n\n/** A unitless length is pixels, as everywhere else on an element. */\nconst length = (value: unknown): string | undefined => {\n  const raw = text(value)\n  if (raw === undefined) return undefined\n  return /^\\d+(\\.\\d+)?$/.test(raw) ? `${raw}px` : raw\n}\n\n/**\n * Reads the settings off an element's props. Anything unreadable is treated\n * as unset rather than thrown on, because a stored document can hold any\n * value and a lightbox that refuses to open over a bad radius is worse than\n * one with square corners.\n */\nexport function readLightboxAppearance(\n  props: Readonly<Record<string, unknown>> | null | undefined,\n): LightboxAppearance {\n  const bag = props ?? {}\n  const P = LIGHTBOX_APPEARANCE_PROPS\n  const appearance: LightboxAppearance = {\n    closeOnBackdrop: onUnlessNo(bag[P.closeOnBackdrop]),\n    closeOnEscape: onUnlessNo(bag[P.closeOnEscape]),\n  }\n  const backdropColor = text(bag[P.backdropColor])\n  if (backdropColor) appearance.backdropColor = backdropColor\n  const backdropOpacity = number(bag[P.backdropOpacity], 0, 100)\n  if (backdropOpacity !== undefined) appearance.backdropOpacity = backdropOpacity\n  const backdropBlur = number(bag[P.backdropBlur], 0, 64)\n  if (backdropBlur !== undefined) appearance.backdropBlur = backdropBlur\n  const maxWidth = length(bag[P.maxWidth])\n  if (maxWidth) appearance.maxWidth = maxWidth\n  const maxHeight = length(bag[P.maxHeight])\n  if (maxHeight) appearance.maxHeight = maxHeight\n  const padding = length(bag[P.padding])\n  if (padding) appearance.padding = padding\n  const radius = number(bag[P.radius], 0, 999)\n  if (radius !== undefined) appearance.radius = radius\n  const closeStyle = oneOf(bag[P.closeStyle], LIGHTBOX_CLOSE_STYLES)\n  if (closeStyle) appearance.closeStyle = closeStyle\n  const closePosition = oneOf(bag[P.closePosition], LIGHTBOX_CLOSE_POSITIONS)\n  if (closePosition) appearance.closePosition = closePosition\n  const captionPlacement = oneOf(\n    bag[P.captionPlacement],\n    LIGHTBOX_CAPTION_PLACEMENTS,\n  )\n  if (captionPlacement) appearance.captionPlacement = captionPlacement\n  const transition = oneOf(bag[P.transition], LIGHTBOX_TRANSITIONS)\n  if (transition) appearance.transition = transition\n  return appearance\n}\n\n/**\n * Splits an element's props into its lightbox settings and everything else,\n * so the rest can be spread onto the element's DOM without a dozen unknown\n * attributes riding along.\n */\nexport function splitLightboxAppearanceProps<T extends object>(\n  props: T,\n): { appearance: LightboxAppearance; rest: Omit<T, LightboxAppearancePropName> } {\n  const rest: Record<string, unknown> = {}\n  const names = new Set<string>(LIGHTBOX_APPEARANCE_PROP_NAMES)\n  for (const [key, value] of Object.entries(props)) {\n    if (!names.has(key)) rest[key] = value\n  }\n  return {\n    appearance: readLightboxAppearance(props as Record<string, unknown>),\n    rest: rest as Omit<T, LightboxAppearancePropName>,\n  }\n}\n\n/**\n * The backdrop's paint: the color at the opacity asked for. A hex color is\n * written as `rgba()`; any other color — a name, an `rgb()`, a theme variable\n * — is mixed with transparency, which every browser that renders the dialog\n * supports. `undefined` when neither is set, so the theme's backdrop stays.\n */\nexport function lightboxBackdropBackground(\n  appearance: Pick<LightboxAppearance, 'backdropColor' | 'backdropOpacity'>,\n): string | undefined {\n  const { backdropColor, backdropOpacity } = appearance\n  if (!backdropColor && backdropOpacity === undefined) return undefined\n  const color = backdropColor ?? '#000000'\n  const opacity = backdropOpacity ?? 80\n  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color)\n  if (hex) {\n    const digits =\n      hex[1].length === 3\n        ? hex[1]\n            .split('')\n            .map((digit) => digit + digit)\n            .join('')\n        : hex[1]\n    const red = parseInt(digits.slice(0, 2), 16)\n    const green = parseInt(digits.slice(2, 4), 16)\n    const blue = parseInt(digits.slice(4, 6), 16)\n    return `rgba(${red}, ${green}, ${blue}, ${opacity / 100})`\n  }\n  return `color-mix(in srgb, ${color} ${opacity}%, transparent)`\n}\n"],"names":["LIGHTBOX_CLOSE_STYLES","LIGHTBOX_CLOSE_POSITIONS","LIGHTBOX_CAPTION_PLACEMENTS","LIGHTBOX_TRANSITIONS","LIGHTBOX_APPEARANCE_PROPS","backdropColor","backdropOpacity","backdropBlur","maxWidth","maxHeight","padding","radius","closeStyle","closePosition","captionPlacement","transition","closeOnBackdrop","closeOnEscape","LIGHTBOX_APPEARANCE_PROP_NAMES","Object","values","LIGHTBOX_APPEARANCE_FIELDS","name","label","description","kind","options","value","text","Number","isFinite","undefined","trimmed","trim","number","min","max","parsed","String","Math","oneOf","allowed","includes","onUnlessNo","length","raw","test","readLightboxAppearance","props","bag","P","appearance","splitLightboxAppearanceProps","rest","names","Set","key","entries","has","lightboxBackdropBackground","color","opacity","hex","exec","digits","split","map","digit","join","red","parseInt","slice","green","blue"],"mappings":"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"}

package/src/lib/components/lightbox/lightbox-dialog.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @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.
+ */
+import { type DialogProps } from '@mui/material/Dialog';
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { KeyboardEvent, ReactNode } from 'react';
+import { type LightboxAppearance } from './lightbox-appearance';
+/** Why the dialog was asked to close. */
+export type LightboxCloseReason = 'escapeKeyDown' | 'backdropClick' | 'closeButton';
+/** The appearance every lightbox takes when an element sets none. */
+export declare const DEFAULT_LIGHTBOX_APPEARANCE: LightboxAppearance;
+export interface LightboxDialogProps {
+    open: boolean;
+    onClose: () => void;
+    /** The dialog's accessible name. Required: an unnamed dialog is a defect. */
+    label: string;
+    /** The close control's accessible name. */
+    closeLabel?: string;
+    appearance?: LightboxAppearance;
+    /**
+     * A chance to refuse one close: return `true` to keep the dialog open. The
+     * Video uses it so `Escape` in full screen leaves full screen first.
+     */
+    interceptClose?: (reason: LightboxCloseReason) => boolean;
+    onKeyDown?: (event: KeyboardEvent<HTMLDivElement>) => void;
+    /**
+     * `false` when the content draws its own {@link LightboxCloseButton} — the
+     * Video does, inside the frame that goes full screen.
+     */
+    closeButton?: boolean;
+    /** The frame's width rule when the appearance names no max width. */
+    maxWidth?: DialogProps['maxWidth'];
+    fullWidth?: boolean;
+    /** Extra styles for the paper — the Video's black ground, for one. */
+    paperSx?: SxProps<Theme>;
+    /** Extra styles for the close control. */
+    closeButtonSx?: SxProps<Theme>;
+    children?: ReactNode;
+}
+/** `prefers-reduced-motion` — the transitions drop to nothing under it. */
+export declare function useLightboxReducedMotion(): boolean;
+export interface LightboxCloseButtonProps {
+    onClick: () => void;
+    label: string;
+    appearance?: LightboxAppearance;
+    sx?: SxProps<Theme>;
+}
+/** The close control: the same one in every lightbox, styled by appearance. */
+export declare function LightboxCloseButton(props: LightboxCloseButtonProps): import("react").JSX.Element;
+export declare namespace LightboxCloseButton {
+    var displayName: string;
+}
+/**
+ * The dialog. Mounted by a caller once armed; renders nothing while closed.
+ */
+export declare function LightboxDialog(props: LightboxDialogProps): import("react").JSX.Element;
+export declare namespace LightboxDialog {
+    var displayName: string;
+}
+/** The frame's inner box, for content that wants the paper's full height. */
+export declare function LightboxFrame(props: {
+    children?: ReactNode;
+    sx?: SxProps<Theme>;
+}): import("react").JSX.Element;
+export default LightboxDialog;