@scenography/overlay-presets 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,337 @@
+import { Overlay, OverlayComponent, OverlayContext, Text } from "@scenography/overlay";
+import { Artwork } from "@scenography/plugin-artwork/data";
+
+//#region src/util.d.ts
+/**
+ * Button/label content: a glyph string, a DOM node (e.g. an SVG icon), or a
+ * factory returning either. A factory is handy for icons that must be a fresh
+ * node each time the content is swapped (a DOM node can only live in one place).
+ */
+type IconContent = string | Node | (() => string | Node);
+//#endregion
+//#region src/lucide.d.ts
+/**
+ * Render a Lucide icon by name as overlay button content.
+ *
+ * Lucide is an OPTIONAL peer dependency: it's imported lazily, so the overlay
+ * works without it. When lucide isn't installed the icon renders empty — install
+ * `lucide`, pass your own `icon` to a prefab, or use `actionButton` if you don't
+ * want the dependency.
+ */
+declare function lucideIcon(name: string, size?: number): IconContent;
+//#endregion
+//#region src/components/fullscreen/fullscreen.d.ts
+interface FullscreenButtonOptions {
+  /** Icons for the enter/exit states. Default to plain glyphs ⛶ / ✕. */
+  icons?: {
+    enter: IconContent;
+    exit: IconContent;
+  };
+  /** Override the daisyUI/utility classes on the button. */
+  className?: string;
+}
+/**
+ * A fullscreen toggle. daisyUI prefab (styled with `btn`). Defaults to plain
+ * glyphs and pulls in no icon library; pass `icons` (e.g. via `lucideIcon` or
+ * your own SVGs) for richer iconography.
+ */
+declare function fullscreenButton(options?: FullscreenButtonOptions): OverlayComponent;
+//#endregion
+//#region src/components/mute/mute.d.ts
+interface MuteButtonOptions {
+  /** Icons for the unmuted/muted states. Default to plain glyphs 🔊 / 🔇. */
+  icons?: {
+    on: IconContent;
+    off: IconContent;
+  };
+  /** Override the daisyUI/utility classes on the button. */
+  className?: string;
+}
+/**
+ * A mute toggle for background audio. daisyUI prefab (styled with `btn`). Drives
+ * `ctx.media` master mute, so it silences every source while keeping their
+ * individual volumes — one click restores the mix exactly. Defaults to plain
+ * glyphs (no icon library); pass `icons` (e.g. `lucideIcon`) for richer icons.
+ */
+declare function muteButton(options?: MuteButtonOptions): OverlayComponent;
+//#endregion
+//#region src/components/cardboard/cardboard.d.ts
+interface CardboardButtonOptions {
+  /** Button icon. Defaults to a plain glyph 🥽. */
+  icon?: IconContent;
+  /** Aria-label. Defaults to "Cardboard mode". */
+  label?: string;
+  /** Override the daisyUI/utility classes on the button. */
+  className?: string;
+}
+/**
+ * A cardboard (stereoscopic) toggle. Flips `ctx.gallery.setRender({ cardboard })`
+ * to split the view into a left/right eye pair for a phone-in-a-headset viewer,
+ * and reflects the on state with daisyUI's `btn-active`. Defaults to a plain
+ * glyph; pass `icon` (e.g. `lucideIcon("RectangleGoggles")`).
+ */
+declare function cardboardButton(options?: CardboardButtonOptions): OverlayComponent;
+//#endregion
+//#region src/components/settings/settings.d.ts
+/** One option in a single-choice section. */
+interface SettingsChoice {
+  value: string;
+  label: Text;
+}
+/** One boolean toggle in the multi-toggle section. */
+interface SettingsToggleItem {
+  key: string;
+  label: Text;
+  value: boolean;
+}
+/**
+ * One single-choice control rendered as a joined row of radio-buttons — a
+ * segmented control (e.g. antialias level, bloom strength).
+ */
+interface SettingsChoiceGroup {
+  key: string;
+  label: Text;
+  /** Current value (matches one option's `value`). */
+  value: string;
+  options: SettingsChoice[];
+  onChange: (value: string) => void;
+}
+/** One numeric slider (range) in the graphics section. */
+interface SettingsSliderItem {
+  key: string;
+  label: Text;
+  value: number;
+  min: number;
+  max: number;
+  /** Step granularity. Defaults to `0.1`. */
+  step?: number;
+  onChange: (value: number) => void;
+}
+interface SettingsPanelOptions {
+  /** Modal title, also the gear button's aria-label. */
+  title: Text;
+  /** Aria-label for the ✕ close button. Defaults to "Close". */
+  closeLabel?: Text;
+  /**
+   * A single-choice section rendered as a `<select>` (e.g. language). Shown in
+   * its own tab; `tab` is the tab's title (falls back to `label`).
+   */
+  language?: {
+    tab?: Text;
+    label: Text;
+    value: string;
+    options: SettingsChoice[];
+    onChange: (value: string) => void;
+  };
+  /** A single-choice section rendered as radios (e.g. handedness). Own tab. */
+  handedness?: {
+    tab?: Text;
+    label: Text;
+    value: string;
+    options: SettingsChoice[];
+    onChange: (value: string) => void;
+  };
+  /** A multi-toggle section (e.g. graphics: ssao / bloom / shadows). Own tab. */
+  graphics?: {
+    tab?: Text;
+    label: Text;
+    items: SettingsToggleItem[];
+    onChange: (key: string, value: boolean) => void; /** Optional segmented radio-button groups above the toggles (e.g. antialias / bloom). */
+    choiceGroups?: SettingsChoiceGroup[]; /** Optional numeric sliders shown below the toggles (e.g. eye separation). */
+    sliders?: SettingsSliderItem[];
+  };
+}
+/**
+ * A settings panel: a ⚙ button that opens a centered daisyUI modal (with an ✕
+ * close, click-outside and Esc). Each section lives in its own tab (the first
+ * present one opens by default). Sections are data — the app supplies labels,
+ * current values and callbacks — so the panel stays generic. Labels are `Text`
+ * and relocalize live via the overlay's locale source. daisyUI + Lucide prefab.
+ */
+declare function settingsPanel(options: SettingsPanelOptions): OverlayComponent;
+//#endregion
+//#region src/components/environment/environment.d.ts
+interface EnvironmentPanelOptions {
+  /** Modal title, also the button's aria-label. */
+  title: Text;
+  /** Aria-label for the ✕ close button. Defaults to "Close". */
+  closeLabel?: Text;
+  /** Button icon. Defaults to a plain glyph ☀. */
+  icon?: IconContent;
+  /** Sliders shown in the modal (e.g. time of day, sun azimuth). */
+  sliders: SettingsSliderItem[];
+  /** Quick presets shown as buttons; each sets one or more sliders by `key`. */
+  presets?: {
+    label: Text;
+    values: Record<string, number>;
+  }[];
+}
+/**
+ * An environment panel: a button (e.g. a sun/cloud icon) opening a daisyUI modal
+ * with sliders for ambient settings like time of day and sun azimuth. Optional
+ * in the default preset — galleries with a procedural sky opt in. daisyUI +
+ * Lucide prefab.
+ */
+declare function environmentPanel(options: EnvironmentPanelOptions): OverlayComponent;
+//#endregion
+//#region src/components/credits/credits.d.ts
+/** One acknowledged asset: what it is, who made it, where it's from. */
+interface CreditItem {
+  /** Discriminant; optional so a plain item needs no `type`. */
+  type?: "item";
+  /** Display name, e.g. "Brick Wall 006". */
+  label: string;
+  /** Author/creator. */
+  author?: string;
+  /** Source URL; turns `label` into a link. */
+  href?: string;
+  /** License, e.g. "CC0". */
+  license?: string;
+}
+/** A labeled separator within a flat list or a tab's children. */
+interface CreditSection {
+  type: "section";
+  /** Section heading, e.g. "Textures". */
+  label: string;
+}
+/** A tab grouping a list of items/sections under a title. */
+interface CreditTab {
+  type: "tab";
+  /** Tab title. */
+  label: string;
+  /** The grouped entries (items and sections; no nested tabs). */
+  children: Array<CreditItem | CreditSection>;
+}
+/** Anything that can appear at the top level of the credits. */
+type CreditEntry = CreditItem | CreditSection | CreditTab;
+interface CreditsPanelOptions {
+  /**
+   * The credited entries. Loose items/sections render first (above the tabs);
+   * tabs render after, as a daisyUI tab strip. A getter is re-read on locale
+   * change to relocalize.
+   */
+  items: CreditEntry[] | (() => CreditEntry[]);
+  /** Panel heading. Defaults to "Credits". */
+  title?: Text;
+  /** Button icon. Defaults to the plain glyph ⓘ. */
+  icon?: IconContent;
+  /** Override the daisyUI/utility classes on the toggle button. */
+  className?: string;
+}
+/**
+ * A credits panel: a button opening a centered daisyUI modal (✕ close,
+ * click-outside, Esc) listing attributions. Entries are data (`items`): loose
+ * items and sections show first; `tab` entries become a daisyUI tab strip below
+ * (first tab open), so an exhibition can credit its author up top and group
+ * assets/technology/etc. into tabs with sectioned lists. Defaults to a plain
+ * glyph icon; pass `icon` (e.g. `lucideIcon`).
+ */
+declare function creditsPanel(options: CreditsPanelOptions): OverlayComponent;
+//#endregion
+//#region src/components/action-button/action-button.d.ts
+interface ActionButtonOptions {
+  /** Click handler; receives the overlay context (gallery, surface, root). */
+  onClick: (ctx: OverlayContext) => void;
+  /** Icon content: a glyph, an SVG node, or a factory. No lucide required. */
+  icon?: IconContent;
+  /** Text label, placed after the icon. */
+  label?: string;
+  /** Accessible label (use it when there's an icon but no text). */
+  ariaLabel?: string;
+  /** Override the daisyUI/utility classes. */
+  className?: string;
+}
+/**
+ * A generic clickable button — the lucide-free alternative to the opinionated
+ * prefabs. Supply any `icon` (glyph, your own SVG, a Lucide icon you wired up)
+ * and an `onClick`. daisyUI prefab (styled with `btn`).
+ */
+declare function actionButton(options: ActionButtonOptions): OverlayComponent;
+//#endregion
+//#region src/components/info/info.d.ts
+interface InfoPanelOptions {
+  /** Modal title, also the ⓘ button's aria-label. */
+  title: Text;
+  /** Body text shown in the modal (e.g. the control instructions). */
+  text: Text;
+  /** Aria-label for the ✕ close button. Defaults to "Close". */
+  closeLabel?: Text;
+}
+/**
+ * An info panel: an ⓘ button that opens a centered daisyUI modal with a title
+ * and a block of text (with an ✕ close, click-outside and Esc). Content is data,
+ * so the app supplies the (already localized) strings. daisyUI + Lucide prefab.
+ */
+declare function infoPanel(options: InfoPanelOptions): OverlayComponent;
+//#endregion
+//#region src/components/artwork-info/artwork-info.d.ts
+interface ArtworkInfoOptions {
+  /** The artworks' data, looked up by `id` on select. Usually `scene.artworks`. */
+  artworks: Artwork[];
+  /** Aria-label for the panel's ✕ close button. Defaults to "Close". */
+  closeLabel?: string;
+  /**
+   * Availability wording shown in the panel. `'for-sale'` reads `forSale`; both
+   * negative states (`'sold'` / `'not-for-sale'`) read `privateCollection`, since
+   * publicly they mean the same: not available. Defaults to English.
+   */
+  availabilityText?: {
+    forSale?: string;
+    privateCollection?: string;
+  };
+  /** Label for the link shown when an artwork has an `href`. Defaults to "View artwork". */
+  linkText?: string;
+}
+/**
+ * The artwork info panel. The engine emits `artwork:select { id }` when you click
+ * a piece's cartela (or the piece itself); this opens a left-hand panel (40%
+ * width, full height, black at 85% alpha) with the full caption and asks the
+ * camera to frame the piece in the free right 60%. Closing with ✕ re-centers the
+ * piece full-width; if the user walks/turns away the engine emits
+ * `artwork:released` and the panel just closes (no camera move).
+ *
+ * Content is data (`artworks`), unlocalized for now. The panel is mounted on the
+ * surface (escaping the overlay grid); the slot element is an inert placeholder.
+ */
+declare function artworkInfo(options: ArtworkInfoOptions): OverlayComponent;
+//#endregion
+//#region src/components/watermark/watermark.d.ts
+interface WatermarkOptions {
+  /** Text shown. Defaults to "scenography". */
+  text?: string;
+  /** Replace the default styling with your own class. */
+  className?: string;
+}
+/**
+ * A small, unobtrusive text watermark (a "brand stamp"). No daisyUI/Lucide — just
+ * a styled element. Defaults to the text "scenography".
+ */
+declare function watermark(options?: WatermarkOptions): OverlayComponent;
+//#endregion
+//#region src/presets/default.d.ts
+interface DefaultPresetOptions {
+  /** Settings panel (language / handedness / graphics); when given, a ⚙ button is added top-right. */
+  settings?: SettingsPanelOptions;
+  /** Environment panel (time of day, sun azimuth); when given, a ☼ button is added top-right. Off by default. */
+  environment?: EnvironmentPanelOptions;
+  /** Info panel (e.g. control instructions); when given, an ⓘ button is added bottom-right, above credits. */
+  info?: InfoPanelOptions;
+  /** Artwork info panel; when given, clicking a piece opens its caption on the left. */
+  artworks?: ArtworkInfoOptions;
+  /** Asset attributions; when given, a credits panel is added bottom-right. */
+  credits?: CreditEntry[] | (() => CreditEntry[]);
+  /** Credits panel title. */
+  creditsTitle?: Text;
+  /** Bottom-left watermark. Defaults to "scenography"; pass `false` to hide it. */
+  watermark?: WatermarkOptions | false;
+}
+/**
+ * The default overlay layout: mute + fullscreen (and a settings ⚙ when given)
+ * top-right; an info ⓘ and a credits panel bottom-right when given. Wired with
+ * Lucide icons — this is the opinionated, batteries-included layer, so the
+ * coupling to daisyUI + Lucide lives here, not in `@scenography/overlay`.
+ */
+declare function defaultPreset(overlay: Overlay, options?: DefaultPresetOptions): void;
+//#endregion
+export { type ActionButtonOptions, type ArtworkInfoOptions, type CardboardButtonOptions, type CreditEntry, type CreditItem, type CreditSection, type CreditTab, type CreditsPanelOptions, type DefaultPresetOptions, type EnvironmentPanelOptions, type FullscreenButtonOptions, type IconContent, type InfoPanelOptions, type MuteButtonOptions, type SettingsChoice, type SettingsChoiceGroup, type SettingsPanelOptions, type SettingsSliderItem, type SettingsToggleItem, type WatermarkOptions, actionButton, artworkInfo, cardboardButton, creditsPanel, defaultPreset, environmentPanel, fullscreenButton, infoPanel, lucideIcon, muteButton, settingsPanel, watermark };
+//# sourceMappingURL=index.d.mts.map