# elise-studio-components ## Custom button events Existing `Button` nodes can opt into click tracking with `eventName`: ```json { "type": "Button", "props": { "content": "Explore floor plans", "action": "navigate", "target": "/floorplans", "eventName": "floorplans_cta_click", "eventCategory": "engagement", "eventParameters": { "placement": "hero", "rank": 1, "featured": true } } } ``` Event names use lowercase snake_case and may be shared by several buttons. Omit `eventName` to disable custom tracking; retained category and parameter settings do not block publishing while tracking is disabled. Category defaults to `engagement`; parameters are optional string, finite number, or boolean values. The keys `event`, `gtm`/`gtm.*`, `ecommerce`, `event_category`, `property_id`, `type`, `asset`, and prototype keys are reserved. Studio treats `type` as a node marker and `asset` as an asset reference; use names such as `button_type` and `asset_name` instead. Property ID comes from the nearest property scope, falling back to the site's property; it is omitted when unavailable. Parameter dictionaries are literal data: binding-like keys such as `$content` are preserved rather than resolved as Studio directives. The shared analytics dispatcher sends the event before the button action, including native external links and document downloads. This measures the click, not a completed download or booking. Native disabled buttons do not track. Existing link and download activation behavior is unchanged. Phone and email links send only their existing automatic `phone_click` or `email_click` event; custom event settings do not apply to these links. Downloads use custom tracking, even when a phone or email target is also configured. Configuration errors are reported during authoring and blocked by the compiler before publishing. Click handlers trust validated configuration; a failing customer tag does not interrupt the custom-tracked button action. Analytics mode, destination routing, and consent handling use the existing site configuration; this feature does not grant consent or install tags. Schema version 41 adds Button tracking fields using the existing `object` kind for event parameters. Release this package first, then update the exact `@meetelise/studio-components` version and lockfiles in both the CRM editor and Studio compiler. The corresponding editor adds tracking controls; the compiler blocks invalid custom tracking at publish and refuses tracked buttons when its installed package lacks this contract. ### Nav button links and Footer actions Nav button links (including buttons in dropdowns) and Footer actions accept the same `eventName`, `eventCategory`, and `eventParameters` and send the same event when clicked. Plain Nav links do not send custom events. Schema version 43 declares the fields on Nav links and schema version 44 on Footer actions; the compiler blocks their tracking errors at publish like a Button's. ## Apply Now and Schedule a Tour buttons `ApplyNowButton` and `ScheduleTourButton` are Buttons with a conversion event prefilled. They take Button presentation props, a `content` label ("Apply Now" / "Schedule a Tour"), an optional `propertyId` that overrides the nearest property scope for the event, and the custom tracking fields of a Button (`eventName`, `eventCategory`, `eventParameters`). The schema defaults `eventName` to `apply_click` / `tour_cta_click` and `eventCategory` to `conversion`, and the editor writes them when the button is inserted; authors can rename the event, add parameters, or turn tracking off by removing `eventName`, as on a Button. A missing `eventCategory` means `conversion`. - `ApplyNowButton`'s default `apply_click` matches the payload unit cards send (`event_category: "conversion"` and `property_id`). It opens its application link in a new tab unless `openInNewTab` is false. The link is the property's CRM `application_link`, read from the site properties request (attributes only, shared by every apply button on the site). An authored `target` (Application URL) overrides it. - `ScheduleTourButton`'s event also carries `tour_type` from `tourType` (`guided`, `sgt`, or `virtual`, matching ScheduleTour; the schema labels them In-Person, Self-Guided, and Virtual). Without a `target` it opens ScheduleTour for its property in a modal, with `tourType` selected when the property offers it; with one it follows `action` and `target` like a Button (a tour page, a modal, or a section). `tour_booking` still means a completed ScheduleTour booking. ApplyNowButton without a URL or CRM link, and ScheduleTourButton without a destination or a property, render nothing on published sites and show a placeholder in the editor. Nav button links and Footer actions can't hold these components; give them the same events with custom tracking (`eventName: "apply_click"` or `"tour_cta_click"` and `eventCategory: "conversion"`). ## Button shapes and icons `Button.radius` (`none`, `sm`, `md`, `lg`, `xl`, `full`) rounds one button on the theme's radius scale without changing `radius.base`, so pill-shaped calls to action can sit beside cards, maps, and modals that keep the theme radius. `Button.icon` names an `Icon` glyph drawn beside the label; `iconPosition` places it at the `start` (default) or `end`. Unknown names render no icon, and document buttons keep their download glyph. Nav button links, Footer actions, ContactForm submit buttons, and FloorplanCatalog actions forward these fields through the shared Button presentation contract. Omitting them preserves the theme radius and text-only label. `Icon` adds `kitchen`, `lounge`, `sun`, `window`, `bus`, `car`, `phone`, `mail`, `map-pin`, and `arrow-right` glyphs. Its optional `color` accepts the same validated colors and `{"$token": "color.primary"}` bindings as other color props; omitted icons inherit the surrounding text color. Schema version 42 adds these fields with the Nav, Gallery, SpecialPromotion, and FloorplanExplorer options below. Release this package first, then update the exact `@meetelise/studio-components` version and lockfiles in both the CRM editor and Studio compiler before authoring them in production. ## Leasing office hours `OfficeHours` reads `attributes.leasing_office_hours_schedule` from the public property API. Each interval contains `day_of_week`, property-local `start_time` and `end_time` (`HH:MM`), and `by_appointment_only`. For a non-empty structured schedule, both layouts render Monday through Sunday, preserving multiple intervals per day and displaying missing days as `Closed`, matching CRM's enabled-day storage. Table and inline layouts format these records directly without parsing human-readable schedules or shifting times to the visitor's timezone. When structured hours are absent or empty, the existing `leasing_office_hours` string takes precedence over authored `hours`; an empty schedule does not imply that all seven days are closed. Both text sources remain intact as text, including when table layout is selected. Deploy the additive API field before updating component-package pins to enable structured tables in consumers. ## Thumbnail carousel galleries Set `Gallery.layout` to `thumbnail-carousel` for a large photo with square previous/next controls and a strip of five visible thumbnails below it. At desktop widths (1024px and up), arrows appear on photo hover or keyboard focus when the device has a fine, hover-capable pointer. Smaller tablet/mobile viewports and touch-only devices hide the arrows; tappable thumbnails remain available alongside swipes. Swipe left/right on the main photo to navigate on touch screens; vertical scrolling and pinch zoom remain available, and a tap opens the lightbox. Clicking a thumbnail selects that photo; the active border and strip stay synchronized with the arrows. Selecting a photo smoothly shifts its thumbnail to the left edge of the strip, stopping at the end so the last five thumbnails stay filled. Overflow supports touch scrolling; only the strip moves, not the surrounding page. Reduced-motion preferences disable the smooth animation. Focused thumbnails support Left/Right arrows and Home/End as well as native Enter/Space activation. This layout supports category filters and independent section galleries, static images and live property media. `carouselAccentColor` controls the arrows and selected border, defaulting to the site's primary theme color. Existing tile height, image fit, radius, and responsive settings still apply; the default stage aspect ratio is 4:3. Clicking the large photo opens the existing lightbox; `lightboxThumbnails` controls only the overlay's optional thumbnail strip. The editor and compiler receive the new layout through the generated component schema (version 37). Release the package and update the consuming editor/compiler versions before selecting this layout in production. ## Scrolling photo strips Set `Gallery.layout` to `strip` for a single row of square photos that scrolls horizontally with snap points. `tileHeight` (with `responsiveTileHeight`) sets each tile's height and width, defaulting to 16rem; `columnGap`, `tileRadius`, `tileFit`, and `edgeBleed` keep their existing meanings. Tiles open the existing lightbox. Touch, trackpad, and keyboard focus scroll the row; on wide screens with a fine, hover-capable pointer, previous/next buttons appear on hover or focus whenever more photos are available in that direction. Category filters and section grouping work as in the other layouts. ## Floor plan rent display `FloorplanExplorer.rentDisplay: "startingAt"` shows the lowest rent with a "Starting at" label on standard cards instead of the full rent range. The default `range` keeps the existing output; marketplace cards already show their starting rent and are unaffected. ## Curated floor plan catalogs `FloorplanCatalog` is a grouped, selector-and-accordion presentation of live Elise floor plans. Each authored plan is a reference to an Elise floor plan id; references missing from the authenticated property API are not rendered. Authored JSON controls group order, marketing copy, actions, optional image fallbacks, and an optional square-footage marketing label. API records remain the source of identity, bed/bath values, availability, rent, and preferred media. The component follows all cursor pages so a curated id is not lost beyond the first response page, and stops safely if the API repeats a cursor. The catalog uses Studio's keyed `sm` through `2xl` responsive contract and a semantic `collapseAt` breakpoint. Actions reuse the canonical Button contract, navigation stays router-aware, analytics emit canonical API floor plan ids, and images use the shared accessible Lightbox. `FloorplanExplorer` remains unchanged for uncurated listing grids and lists. A validated `compactPresentation` object controls accordion typography, rhythm, panel insets, and action alignment below the collapse breakpoint without relying on arbitrary classes or site templates. The opt-in `desktopPresentation: "workspace"` mode integrates a bounded, scrollable grouped selector with a stable summary-and-drawing canvas for larger catalogs. Selector headings, counts, and API-backed plan details are separately configurable. Below `collapseAt`, `compactDisclosure: "single"` turns the same catalog into a globally single-open inline accordion; responsive detail columns and connected panel styling remain authored presentation choices. The default `split`/`perGroup` behavior and API contract are unchanged. ## Motion and background media `BackgroundMedia` is a generic frame for decorative image or muted video backgrounds. It accepts normal Studio children, so headings, buttons, and data components remain independently editable. The optional `parallax` motion moves only the media layer; overlay content and document layout stay fixed. Video is paused outside the viewport and replaced by its poster or image when the visitor requests reduced motion. If no still is authored, a paused first video frame is used instead. ```json { "type": "BackgroundMedia", "props": { "video": { "$content": "hero.video" }, "poster": { "$content": "hero.poster" }, "minHeight": "90vh", "contentPosition": "bottom-left", "motion": "parallax" }, "children": [ { "type": "Text", "props": { "content": { "$content": "hero.headline" }, "variant": "display" } } ] } ``` `Parallax` applies the same bounded, request-animation-frame scroll transform to any child subtree. `StickyFrame` pins a subtree within its parent scroll range and defaults to normal flow on mobile. Together with `Grid`, `Container`, and `ScrollReveal`, these frames support sticky storytelling, independently moving media, and layered editorial sections without site-specific JavaScript or CSS. All motion is progressive enhancement: server output remains visible, unsupported browsers retain a static layout, and operating-system reduced-motion preferences disable continuous translation. ## Atlas authoring contract The exported component schema includes optional `authoring` metadata for Atlas and semantic validators. It describes component roles, breakpoint-aware props, composition constraints, required context, relative performance cost, stable repair hints, and recommended recipe IDs. Runtime rendering ignores this metadata. The generated `dist/componentSchema.json` versions the component schema, authoring contract, and diagnostic envelope independently. Diagnostics use a shared shape and may include existing Studio design operations for Atlas to apply: ```json { "code": "STICKY_MEDIA_OVERLAP", "severity": "error", "nodeId": "hero-media", "breakpoint": "sm", "message": "The transformed media can leave its sticky boundary.", "suggestedOperations": [ { "type": "set_node_prop", "node_id": "hero-media", "prop_path": ["motion"], "value": "none" } ] } ``` `validateAuthoringTree` is the shared, side-effect-free semantic validator used by Atlas, preview, and compiler consumers. It checks required props, component nesting, authoring contexts, incompatibilities, deprecations, and an optional normalized performance budget without resolving or rendering the tree: ```ts const { diagnostics, performanceCost } = validateAuthoringTree(page.tree, { availableContexts: ["property"], performanceBudget: 24, path: "pages[0].tree", }); ``` Errors represent invalid authoring decisions; warnings cover deprecations, unknown props, and budget pressure. When a safe default exists, a diagnostic may include a typed Studio design operation that Atlas can apply as a repair. ## Atlas composition recipes The `@meetelise/studio-components/recipes` export and generated `dist/authoringRecipes.json` provide versioned, validated section blueprints. Each recipe declares its content fields, required site contexts, normalized performance budget, and a normal Studio component tree using `$content` bindings. The initial catalog includes editorial hero, split-media story, sticky-media story, and availability/conversion compositions. Recipes are build-validated against the canonical component schema and semantic validator. A build fails if a recipe references an unknown component, an undeclared content key, or a missing recipe ID. Atlas can therefore select a recipe, create its declared content fields, and insert the tree through ordinary typed Studio operations. ## Amenity presentations `AmenityList` keeps layout and ordering independent. Existing sites continue to use the alphabetized icon-grid default, while `order="source"` preserves the first occurrence of each amenity from either authored content or the Elise property API. The opt-in `bulleted` layout emits semantic `ul`/`li` markup and uses theme body typography. Its indentation, item spacing, and typography can be adjusted through the validated `bulletPresentation` object without baking a property's measurements into the shared component. ## Overlay navigation below preceding content Use `Container display="grid" overlapChildren` to layer navigation over page content while earlier content, such as a specials banner, stays in document flow: ```tsx