@aceshooting/lyra-ui 11.1.0 → 12.0.0

package/dist/components/data/graph-query-builder/graph-query-builder.class.d.ts

@@ -1,6 +1,7 @@
 import type { LyraEventDetailSnapshot } from '../../../internal/lyra-element.js';
 import { type TemplateResult, type PropertyValues } from 'lit';
 import { LyraElement } from '../../../internal/lyra-element.js';
+import '../../../internal/form-control-labels.js';
 import { type FormOwnerValue } from '../../../internal/form-associated.js';
 /** Traversal direction relative to the matched node(s): `'out'` (outgoing edges), `'in'`
  *  (incoming edges), or `'both'`. */

package/dist/components/data/graph-query-builder/graph-query-builder.class.js

@@ -1,4 +1,4 @@
-var __decorate=function(decorators,target,key,desc){var c=arguments.length,r=c<3?target:desc===null?desc=Object.getOwnPropertyDescriptor(target,key):desc,d;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(decorators,target,key,desc);else for(var i=decorators.length-1;i>=0;i--)(d=decorators[i])&&(r=(c<3?d(r):c>3?d(target,key,r):d(target,key))||r);return c>3&&r&&Object.defineProperty(target,key,r),r};import{html,nothing}from"lit";import{property,state}from"lit/decorators.js";import{LyraElement}from"../../../internal/lyra-element.js";import{closeIcon}from"../../../internal/icons.js";import{AnchoredValidityController,VALIDITY_ANCHOR}from"../../../internal/anchored-validity.js";import{syncValidityStates}from"../../../internal/custom-states.js";import{finiteInteger}from"../../../internal/numbers.js";import{getNumberFormat}from"../../../internal/intl-cache.js";import{nextId}from"../../../internal/a11y.js";import{deepActiveElementIn}from"../../../internal/active-element.js";import{styles}from"./graph-query-builder.styles.js";import{attachInternalsSafely}from"../../../internal/element-internals.js";import{getFormOwner,installCustomErrorProperty,isBarredFromValidation,setFormOwner}from"../../../internal/form-associated.js";import{installInvalidEventAlias}from"../../../internal/invalid-event-alias.js";import{LYRA_DEFAULT_fieldRequired,LYRA_DEFAULT_graphQueryBuilderLabel,LYRA_DEFAULT_graphQueryDeleteWithContext,LYRA_DEFAULT_graphQueryDirectionLabel,LYRA_DEFAULT_graphQueryEndLabel,LYRA_DEFAULT_graphQueryHopRangeInvalid,LYRA_DEFAULT_graphQueryLoadWithContext,LYRA_DEFAULT_graphQueryMaxHopsLabel,LYRA_DEFAULT_graphQueryMinHopsLabel,LYRA_DEFAULT_graphQueryNodeTypeLabel,LYRA_DEFAULT_graphQueryRelationshipTypeLabel,LYRA_DEFAULT_graphQueryRun,LYRA_DEFAULT_graphQuerySaveButton,LYRA_DEFAULT_graphQuerySaveNameLabel,LYRA_DEFAULT_graphQuerySavedQueriesLabel,LYRA_DEFAULT_graphQueryStartLabel,LYRA_DEFAULT_neighborDirectionBoth,LYRA_DEFAULT_neighborDirectionIn,LYRA_DEFAULT_neighborDirectionOut,LYRA_DEFAULT_noData,LYRA_DEFAULT_select}from"../../../internal/default-strings.generated.js";const MAX_TYPES=500,MAX_SAVED_QUERIES=200,MAX_TEXT=256,EMPTY_STRINGS=Object.freeze([]),EMPTY_VALUE=Object.freeze({startId:"",endId:"",relationshipTypes:EMPTY_STRINGS,nodeTypes:EMPTY_STRINGS,direction:"both",minHops:1,maxHops:1}),EMPTY_OPTIONS=Object.freeze([]),EMPTY_SAVED=Object.freeze([]);function ownValue(record,key){try{const descriptor=Object.getOwnPropertyDescriptor(record,key);return descriptor&&"value"in descriptor?descriptor.value:void 0}catch{return}}function boundedString(value){return typeof value=="string"?value.slice(0,MAX_TEXT):""}function stringArray(value){return Array.isArray(value)?Object.freeze([...new Set(value.slice(0,MAX_TYPES).filter(entry=>typeof entry=="string").map(entry=>boundedString(entry)).filter(Boolean))]):EMPTY_STRINGS}function normalizeGraphQuery(value){const record=value!==null&&typeof value=="object"&&!Array.isArray(value)?value:EMPTY_VALUE,direction=ownValue(record,"direction");return Object.freeze({startId:boundedString(ownValue(record,"startId")),endId:boundedString(ownValue(record,"endId")),relationshipTypes:stringArray(ownValue(record,"relationshipTypes")),nodeTypes:stringArray(ownValue(record,"nodeTypes")),direction:direction==="out"||direction==="in"||direction==="both"?direction:"both",minHops:finiteInteger(typeof ownValue(record,"minHops")=="number"?ownValue(record,"minHops"):EMPTY_VALUE.minHops,EMPTY_VALUE.minHops,1,20),maxHops:finiteInteger(typeof ownValue(record,"maxHops")=="number"?ownValue(record,"maxHops"):EMPTY_VALUE.maxHops,EMPTY_VALUE.maxHops,1,20)})}function normalizeTypeOptions(value){if(!Array.isArray(value))return EMPTY_OPTIONS;const values=new Set,result=[];for(const candidate of value.slice(0,MAX_TYPES)){if(candidate===null||typeof candidate!="object"||Array.isArray(candidate))continue;const optionValue=boundedString(ownValue(candidate,"value"));if(optionValue.trim().length===0||values.has(optionValue))continue;values.add(optionValue);const label=boundedString(ownValue(candidate,"label"));result.push(Object.freeze({value:optionValue,...label?{label}:{}}))}return Object.freeze(result)}function normalizeSavedQueries(value){if(!Array.isArray(value))return EMPTY_SAVED;const ids=new Set,result=[];for(const candidate of value.slice(0,MAX_SAVED_QUERIES)){if(candidate===null||typeof candidate!="object"||Array.isArray(candidate))continue;const id=boundedString(ownValue(candidate,"id"));id.trim().length===0||ids.has(id)||(ids.add(id),result.push(Object.freeze({id,name:boundedString(ownValue(candidate,"name")),query:normalizeGraphQuery(ownValue(candidate,"query"))})))}return Object.freeze(result)}class LyraGraphQueryBuilder extends LyraElement{static{this.defaultStrings={...super.defaultStrings,fieldRequired:LYRA_DEFAULT_fieldRequired,graphQueryBuilderLabel:LYRA_DEFAULT_graphQueryBuilderLabel,graphQueryDeleteWithContext:LYRA_DEFAULT_graphQueryDeleteWithContext,graphQueryDirectionLabel:LYRA_DEFAULT_graphQueryDirectionLabel,graphQueryEndLabel:LYRA_DEFAULT_graphQueryEndLabel,graphQueryHopRangeInvalid:LYRA_DEFAULT_graphQueryHopRangeInvalid,graphQueryLoadWithContext:LYRA_DEFAULT_graphQueryLoadWithContext,graphQueryMaxHopsLabel:LYRA_DEFAULT_graphQueryMaxHopsLabel,graphQueryMinHopsLabel:LYRA_DEFAULT_graphQueryMinHopsLabel,graphQueryNodeTypeLabel:LYRA_DEFAULT_graphQueryNodeTypeLabel,graphQueryRelationshipTypeLabel:LYRA_DEFAULT_graphQueryRelationshipTypeLabel,graphQueryRun:LYRA_DEFAULT_graphQueryRun,graphQuerySaveButton:LYRA_DEFAULT_graphQuerySaveButton,graphQuerySaveNameLabel:LYRA_DEFAULT_graphQuerySaveNameLabel,graphQuerySavedQueriesLabel:LYRA_DEFAULT_graphQuerySavedQueriesLabel,graphQueryStartLabel:LYRA_DEFAULT_graphQueryStartLabel,neighborDirectionBoth:LYRA_DEFAULT_neighborDirectionBoth,neighborDirectionIn:LYRA_DEFAULT_neighborDirectionIn,neighborDirectionOut:LYRA_DEFAULT_neighborDirectionOut,noData:LYRA_DEFAULT_noData,select:LYRA_DEFAULT_select}}static{this.formAssociated=!0}static{this.styles=[LyraElement.styles,styles]}static{this.immutableEventDetails=Object.freeze(["lr-input","lr-before-query-run","lr-query-run","lr-before-query-save","lr-query-save","lr-before-query-load","lr-query-load"])}static{this.properties={customError:{attribute:"custom-error",reflect:!0,noAccessor:!0},name:{reflect:!0,noAccessor:!0},value:{attribute:!1,noAccessor:!0},disabled:{type:Boolean,reflect:!0,noAccessor:!0}}}get relationshipTypeOptions(){return this._relationshipTypeOptions}set relationshipTypeOptions(value){const previous=this._relationshipTypeOptions;this._relationshipTypeOptions=normalizeTypeOptions(value),this.requestUpdate("relationshipTypeOptions",previous)}get nodeTypeOptions(){return this._nodeTypeOptions}set nodeTypeOptions(value){const previous=this._nodeTypeOptions;this._nodeTypeOptions=normalizeTypeOptions(value),this.requestUpdate("nodeTypeOptions",previous)}get savedQueries(){return this._savedQueries}set savedQueries(value){const previous=this._savedQueries;this._savedQueries=normalizeSavedQueries(value),this.requestUpdate("savedQueries",previous)}constructor(){super(),this._relationshipTypeOptions=EMPTY_OPTIONS,this._nodeTypeOptions=EMPTY_OPTIONS,this._savedQueries=EMPTY_SAVED,this.hopLimit=6,this.label="",this.hint="",this.errorText="",this._errors={},this.touchedFields=new Set,this.saveName="",this.hasHintSlot=!1,this.hasErrorSlot=!1,this.labelId=nextId("graph-query-builder-label"),this.hintId=nextId("graph-query-builder-hint"),this.errorId=nextId("graph-query-builder-error"),this._fieldsetDisabled=!1,this._name="",this._value=EMPTY_VALUE,this.defaultValue=normalizeGraphQuery(EMPTY_VALUE),this.defaultValueCaptured=!1,this._disabled=!1,this.hasInteracted=!1,this.removalFocusGeneration=0,this.onChromeSlotChange=event=>{const slot=event.currentTarget,hasContent=slot.assignedNodes({flatten:!0}).some(node=>node.nodeType===Node.TEXT_NODE?!!node.textContent?.trim():!0);slot.name==="hint"?this.hasHintSlot=hasContent:slot.name==="error"&&(this.hasErrorSlot=hasContent)},this.internals=attachInternalsSafely(this),this.validityController=new AnchoredValidityController(this,this.internals,()=>this[VALIDITY_ANCHOR]()),installCustomErrorProperty(this,()=>this.validityController.customValidityMessage),installInvalidEventAlias(this,init=>this.emit("lr-invalid",null,init)),this.syncFormState()}disconnectedCallback(){this.removalFocusGeneration++,this.pendingRemovalFocus=void 0,super.disconnectedCallback()}get form(){return getFormOwner(this.internals)}set form(owner){setFormOwner(this,owner)}getForm(){return getFormOwner(this.internals)}get labels(){return this.internals.labels}get validity(){return this.internals.validity}get validationMessage(){return this.internals.validationMessage}get willValidate(){return this.internals.willValidate}get value(){return this._value}set value(next){const old=this._value;this._value=normalizeGraphQuery(next),this.syncFormState(),this.requestUpdate("value",old)}get name(){return this._name}set name(next){const old=this._name;this._name=next??"",this._name?this.setAttribute("name",this._name):this.removeAttribute("name"),this.requestUpdate("name",old)}get disabled(){return this._disabled}set disabled(next){const old=this._disabled;this._disabled=!!next,this.toggleAttribute("disabled",this._disabled),this.validityController&&this.syncFormState(),this.requestUpdate("disabled",old)}get effectiveDisabled(){return this.disabled||this._fieldsetDisabled}get errors(){return this.publicValidityErrors()}publicValidityErrors(){const errors={...this._errors};return this.willValidate&&this.validity.customError&&(errors.base=this.validationMessage),Object.freeze(errors)}publishValiditySnapshot(){if(!this.isConnected)return;const valid=!this.willValidate||this.validity.valid,errors=valid?Object.freeze({}):this.publicValidityErrors(),key=JSON.stringify({valid,errors});key!==this.lastValidityKey&&(this.lastValidityKey=key,this.emit("lr-validity-change",Object.freeze({valid,errors})))}[VALIDITY_ANCHOR](){const firstInvalidPart=Object.keys(this._errors)[0];if(!(!firstInvalidPart||!this.renderRoot))return this.renderRoot.querySelector(`[part="${firstInvalidPart}"]`)??void 0}computeValidation(){const errors={},flags={};return this._value.startId.trim()||(errors["start-input"]=this.localize("fieldRequired"),flags.valueMissing=!0),this._value.minHops>this._value.maxHops&&(errors["max-hops"]=this.localize("graphQueryHopRangeInvalid"),flags.rangeUnderflow=!0),{errors,flags}}syncFormState(){const{errors,flags}=this.computeValidation();this._errors=errors;let formValue=null;try{formValue=JSON.stringify(this._value)}catch{formValue=null}if(this.internals.setFormValue(formValue,formValue),this.barredFromValidation||Object.keys(flags).length===0)this.validityController.setValidity({});else{const message=Object.values(errors)[0]??"";this.validityController.setValidity(flags,message)}this.syncValidityCustomStates(),this.publishValiditySnapshot()}get barredFromValidation(){return isBarredFromValidation(this,this.internals)}syncValidityCustomStates(){syncValidityStates(this.internals,{required:!0,hasInteracted:this.hasInteracted,barred:this.barredFromValidation})}checkValidity(){return this.syncFormState(),this.internals.checkValidity()}reportValidity(){return this.hasInteracted=!0,this.syncFormState(),Object.keys(this._errors).length>0&&(this.touchedFields=new Set([...this.touchedFields,...Object.keys(this._errors)])),this.internals.reportValidity()}setCustomValidity(message){this.validityController.setCustomValidity(message??""),this.syncValidityCustomStates(),this.publishValiditySnapshot()}formResetCallback(){this.hasInteracted=!1,this.captureDefaultValue(),this.value=this.defaultValue,this.touchedFields=new Set,this.saveName=""}captureDefaultValue(){this.defaultValueCaptured||(this.defaultValue=normalizeGraphQuery(this._value),this.defaultValueCaptured=!0)}formStateRestoreCallback(state2,_mode){let restored=EMPTY_VALUE;if(typeof state2=="string")try{const parsed=JSON.parse(state2);parsed!==null&&typeof parsed=="object"&&!Array.isArray(parsed)&&(restored=normalizeGraphQuery(parsed))}catch{}this.value=restored}formDisabledCallback(disabled){this._fieldsetDisabled=disabled,this.syncFormState(),this.requestUpdate()}get liveDisabled(){return this.effectiveDisabled||this.matches(":disabled")}focusFirstControl(options){if(!this.renderRoot||this.liveDisabled)return;(this.renderRoot.querySelector('[part="start-input"]')||this.renderRoot.querySelector('[part="end-input"]')||this.renderRoot.querySelector('[part="min-hops"]')||this.renderRoot.querySelector('[part="max-hops"]')||this.renderRoot.querySelector('[part="direction"]')||this.renderRoot.querySelector('[part="save-name-input"]'))?.focus(options)}focus(options){this.focusFirstControl(options)}blur(){const active=deepActiveElementIn(this.shadowRoot);active&&typeof active.blur=="function"&&active.blur()}click(){this.focusFirstControl()}setValue(next){this.effectiveDisabled||(this.hasInteracted=!0,this.value=next,this.emit("lr-input",Object.freeze({value:this._value})))}addRelationshipType(type){!type||this._value.relationshipTypes.includes(type)||this.setValue({...this._value,relationshipTypes:[...this._value.relationshipTypes,type]})}removeRelationshipType(type){this.captureChipRemovalFocus("relationship",type,this._value.relationshipTypes),this.setValue({...this._value,relationshipTypes:this._value.relationshipTypes.filter(t=>t!==type)})}addNodeType(type){!type||this._value.nodeTypes.includes(type)||this.setValue({...this._value,nodeTypes:[...this._value.nodeTypes,type]})}removeNodeType(type){this.captureChipRemovalFocus("node-type",type,this._value.nodeTypes),this.setValue({...this._value,nodeTypes:this._value.nodeTypes.filter(t=>t!==type)})}captureChipRemovalFocus(group,value,selected){const active=this.shadowRoot?.activeElement,expectedPart=group==="relationship"?"relationship-chips":"node-type-chips";if(active?.localName!=="lr-chip"||active.getAttribute("value")!==value||active.closest("lr-chip-group")?.getAttribute("part")!==expectedPart)return;const index=selected.indexOf(value),survivors=selected.filter(candidate=>candidate!==value),targetValue=survivors[Math.min(Math.max(index,0),survivors.length-1)];this.pendingRemovalFocus={kind:"chip",group,targetValue},this.removalFocusGeneration++}markTouched(part){this.hasInteracted=!0,this.syncValidityCustomStates(),!this.touchedFields.has(part)&&(this.touchedFields=new Set(this.touchedFields).add(part))}runQuery(){if(this.effectiveDisabled||!this.reportValidity())return;const detail=()=>Object.freeze({query:normalizeGraphQuery(this._value)});this.emit("lr-before-query-run",detail(),{cancelable:!0}).defaultPrevented||this.emit("lr-query-run",detail())}saveQuery(){if(this.effectiveDisabled)return;const name=this.saveName.trim();if(!name)return;const detail=()=>Object.freeze({name,query:normalizeGraphQuery(this._value)});this.emit("lr-before-query-save",detail(),{cancelable:!0}).defaultPrevented||(this.saveName="",this.emit("lr-query-save",detail()))}loadQuery(item){if(this.effectiveDisabled)return;const detail=()=>Object.freeze({queryId:item.id,query:normalizeGraphQuery(item.query)});this.emit("lr-before-query-load",detail(),{cancelable:!0}).defaultPrevented||(this.setValue({...EMPTY_VALUE,...item.query}),this.emit("lr-query-load",detail()))}deleteQuery(item){if(this.effectiveDisabled)return;const detail=()=>Object.freeze({queryId:item.id});this.emit("lr-before-query-delete",detail(),{cancelable:!0}).defaultPrevented||this.emit("lr-query-delete",detail())}willUpdate(changed){if(super.willUpdate(changed),this.hasUpdated||this.captureDefaultValue(),!changed.has("savedQueries"))return;const active=this.shadowRoot?.activeElement;if(active?.getAttribute("part")!=="saved-delete-button")return;const focusedId=active.closest("[data-query-id]")?.dataset.queryId;if(!focusedId||this.savedQueries.some(item=>item.id===focusedId))return;const index=(changed.get("savedQueries")??[]).findIndex(item=>item.id===focusedId),target=this.savedQueries[Math.min(Math.max(index,0),this.savedQueries.length-1)];this.pendingRemovalFocus={kind:"saved",targetId:target?.id},this.removalFocusGeneration++}updated(changed){super.updated(changed),this.publishValiditySnapshot();const pending=this.pendingRemovalFocus;if(!pending)return;this.pendingRemovalFocus=void 0;const generation=this.removalFocusGeneration;this.scheduleAfterUpdate(()=>{if(!(generation!==this.removalFocusGeneration||!this.isConnected)){if(pending.kind==="chip"){if(pending.targetValue){const part=pending.group==="relationship"?"relationship-chips":"node-type-chips",chip=[...this.shadowRoot?.querySelectorAll(`[part="${part}"] lr-chip`)??[]].find(candidate=>candidate.getAttribute("value")===pending.targetValue);if(chip){chip.focus();return}}const pickerPart=pending.group==="relationship"?"relationship-picker":"node-type-picker";this.shadowRoot?.querySelector(`[part="${pickerPart}"]`)?.focus();return}if(pending.targetId){const action=[...this.shadowRoot?.querySelectorAll("[data-query-id]")??[]].find(candidate=>candidate.dataset.queryId===pending.targetId)?.querySelector('[part="saved-delete-button"]');if(action){action.focus();return}}this.shadowRoot?.querySelector('[part="save-name-input"]')?.focus()}},"graph-query-removal-focus")}hopOptions(){const limit=finiteInteger(this.hopLimit,6,1,20),options=new Set(Array.from({length:limit},(_,i)=>i+1));return options.add(this._value.minHops),options.add(this._value.maxHops),[...options].sort((a,b)=>a-b)}labelForType(options,value){return options.find(o=>o.value===value)?.label??value}renderTypeFilter(kind,options,selected,add,remove,disabled){const pickerPart=kind==="relationship"?"relationship-picker":"node-type-picker",chipsPart=kind==="relationship"?"relationship-chips":"node-type-chips",pickerLabel=kind==="relationship"?this.localize("graphQueryRelationshipTypeLabel"):this.localize("graphQueryNodeTypeLabel"),available=options.filter(o=>!selected.includes(o.value));return html`
+var __decorate=function(decorators,target,key,desc){var c=arguments.length,r=c<3?target:desc===null?desc=Object.getOwnPropertyDescriptor(target,key):desc,d;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(decorators,target,key,desc);else for(var i=decorators.length-1;i>=0;i--)(d=decorators[i])&&(r=(c<3?d(r):c>3?d(target,key,r):d(target,key))||r);return c>3&&r&&Object.defineProperty(target,key,r),r};import{html,nothing}from"lit";import{property,state}from"lit/decorators.js";import{LyraElement}from"../../../internal/lyra-element.js";import"../../../internal/form-control-labels.js";import{closeIcon}from"../../../internal/icons.js";import{AnchoredValidityController,VALIDITY_ANCHOR}from"../../../internal/anchored-validity.js";import{syncValidityStates}from"../../../internal/custom-states.js";import{finiteInteger}from"../../../internal/numbers.js";import{getNumberFormat}from"../../../internal/intl-cache.js";import{nextId}from"../../../internal/a11y.js";import{deepActiveElementIn}from"../../../internal/active-element.js";import{styles}from"./graph-query-builder.styles.js";import{attachInternalsSafely}from"../../../internal/element-internals.js";import{getFormOwner,installCustomErrorProperty,isBarredFromValidation,setFormOwner}from"../../../internal/form-associated.js";import{installInvalidEventAlias}from"../../../internal/invalid-event-alias.js";import{LYRA_DEFAULT_fieldRequired,LYRA_DEFAULT_graphQueryBuilderLabel,LYRA_DEFAULT_graphQueryDeleteWithContext,LYRA_DEFAULT_graphQueryDirectionLabel,LYRA_DEFAULT_graphQueryEndLabel,LYRA_DEFAULT_graphQueryHopRangeInvalid,LYRA_DEFAULT_graphQueryLoadWithContext,LYRA_DEFAULT_graphQueryMaxHopsLabel,LYRA_DEFAULT_graphQueryMinHopsLabel,LYRA_DEFAULT_graphQueryNodeTypeLabel,LYRA_DEFAULT_graphQueryRelationshipTypeLabel,LYRA_DEFAULT_graphQueryRun,LYRA_DEFAULT_graphQuerySaveButton,LYRA_DEFAULT_graphQuerySaveNameLabel,LYRA_DEFAULT_graphQuerySavedQueriesLabel,LYRA_DEFAULT_graphQueryStartLabel,LYRA_DEFAULT_neighborDirectionBoth,LYRA_DEFAULT_neighborDirectionIn,LYRA_DEFAULT_neighborDirectionOut,LYRA_DEFAULT_noData,LYRA_DEFAULT_select}from"../../../internal/default-strings.generated.js";const MAX_TYPES=500,MAX_SAVED_QUERIES=200,MAX_TEXT=256,EMPTY_STRINGS=Object.freeze([]),EMPTY_VALUE=Object.freeze({startId:"",endId:"",relationshipTypes:EMPTY_STRINGS,nodeTypes:EMPTY_STRINGS,direction:"both",minHops:1,maxHops:1}),EMPTY_OPTIONS=Object.freeze([]),EMPTY_SAVED=Object.freeze([]);function ownValue(record,key){try{const descriptor=Object.getOwnPropertyDescriptor(record,key);return descriptor&&"value"in descriptor?descriptor.value:void 0}catch{return}}function boundedString(value){return typeof value=="string"?value.slice(0,MAX_TEXT):""}function stringArray(value){return Array.isArray(value)?Object.freeze([...new Set(value.slice(0,MAX_TYPES).filter(entry=>typeof entry=="string").map(entry=>boundedString(entry)).filter(Boolean))]):EMPTY_STRINGS}function normalizeGraphQuery(value){const record=value!==null&&typeof value=="object"&&!Array.isArray(value)?value:EMPTY_VALUE,direction=ownValue(record,"direction");return Object.freeze({startId:boundedString(ownValue(record,"startId")),endId:boundedString(ownValue(record,"endId")),relationshipTypes:stringArray(ownValue(record,"relationshipTypes")),nodeTypes:stringArray(ownValue(record,"nodeTypes")),direction:direction==="out"||direction==="in"||direction==="both"?direction:"both",minHops:finiteInteger(typeof ownValue(record,"minHops")=="number"?ownValue(record,"minHops"):EMPTY_VALUE.minHops,EMPTY_VALUE.minHops,1,20),maxHops:finiteInteger(typeof ownValue(record,"maxHops")=="number"?ownValue(record,"maxHops"):EMPTY_VALUE.maxHops,EMPTY_VALUE.maxHops,1,20)})}function normalizeTypeOptions(value){if(!Array.isArray(value))return EMPTY_OPTIONS;const values=new Set,result=[];for(const candidate of value.slice(0,MAX_TYPES)){if(candidate===null||typeof candidate!="object"||Array.isArray(candidate))continue;const optionValue=boundedString(ownValue(candidate,"value"));if(optionValue.trim().length===0||values.has(optionValue))continue;values.add(optionValue);const label=boundedString(ownValue(candidate,"label"));result.push(Object.freeze({value:optionValue,...label?{label}:{}}))}return Object.freeze(result)}function normalizeSavedQueries(value){if(!Array.isArray(value))return EMPTY_SAVED;const ids=new Set,result=[];for(const candidate of value.slice(0,MAX_SAVED_QUERIES)){if(candidate===null||typeof candidate!="object"||Array.isArray(candidate))continue;const id=boundedString(ownValue(candidate,"id"));id.trim().length===0||ids.has(id)||(ids.add(id),result.push(Object.freeze({id,name:boundedString(ownValue(candidate,"name")),query:normalizeGraphQuery(ownValue(candidate,"query"))})))}return Object.freeze(result)}class LyraGraphQueryBuilder extends LyraElement{static{this.defaultStrings={...super.defaultStrings,fieldRequired:LYRA_DEFAULT_fieldRequired,graphQueryBuilderLabel:LYRA_DEFAULT_graphQueryBuilderLabel,graphQueryDeleteWithContext:LYRA_DEFAULT_graphQueryDeleteWithContext,graphQueryDirectionLabel:LYRA_DEFAULT_graphQueryDirectionLabel,graphQueryEndLabel:LYRA_DEFAULT_graphQueryEndLabel,graphQueryHopRangeInvalid:LYRA_DEFAULT_graphQueryHopRangeInvalid,graphQueryLoadWithContext:LYRA_DEFAULT_graphQueryLoadWithContext,graphQueryMaxHopsLabel:LYRA_DEFAULT_graphQueryMaxHopsLabel,graphQueryMinHopsLabel:LYRA_DEFAULT_graphQueryMinHopsLabel,graphQueryNodeTypeLabel:LYRA_DEFAULT_graphQueryNodeTypeLabel,graphQueryRelationshipTypeLabel:LYRA_DEFAULT_graphQueryRelationshipTypeLabel,graphQueryRun:LYRA_DEFAULT_graphQueryRun,graphQuerySaveButton:LYRA_DEFAULT_graphQuerySaveButton,graphQuerySaveNameLabel:LYRA_DEFAULT_graphQuerySaveNameLabel,graphQuerySavedQueriesLabel:LYRA_DEFAULT_graphQuerySavedQueriesLabel,graphQueryStartLabel:LYRA_DEFAULT_graphQueryStartLabel,neighborDirectionBoth:LYRA_DEFAULT_neighborDirectionBoth,neighborDirectionIn:LYRA_DEFAULT_neighborDirectionIn,neighborDirectionOut:LYRA_DEFAULT_neighborDirectionOut,noData:LYRA_DEFAULT_noData,select:LYRA_DEFAULT_select}}static{this.formAssociated=!0}static{this.styles=[LyraElement.styles,styles]}static{this.immutableEventDetails=Object.freeze(["lr-input","lr-before-query-run","lr-query-run","lr-before-query-save","lr-query-save","lr-before-query-load","lr-query-load"])}static{this.properties={customError:{attribute:"custom-error",reflect:!0,noAccessor:!0},name:{reflect:!0,noAccessor:!0},value:{attribute:!1,noAccessor:!0},disabled:{type:Boolean,reflect:!0,noAccessor:!0}}}get relationshipTypeOptions(){return this._relationshipTypeOptions}set relationshipTypeOptions(value){const previous=this._relationshipTypeOptions;this._relationshipTypeOptions=normalizeTypeOptions(value),this.requestUpdate("relationshipTypeOptions",previous)}get nodeTypeOptions(){return this._nodeTypeOptions}set nodeTypeOptions(value){const previous=this._nodeTypeOptions;this._nodeTypeOptions=normalizeTypeOptions(value),this.requestUpdate("nodeTypeOptions",previous)}get savedQueries(){return this._savedQueries}set savedQueries(value){const previous=this._savedQueries;this._savedQueries=normalizeSavedQueries(value),this.requestUpdate("savedQueries",previous)}constructor(){super(),this._relationshipTypeOptions=EMPTY_OPTIONS,this._nodeTypeOptions=EMPTY_OPTIONS,this._savedQueries=EMPTY_SAVED,this.hopLimit=6,this.label="",this.hint="",this.errorText="",this._errors={},this.touchedFields=new Set,this.saveName="",this.hasHintSlot=!1,this.hasErrorSlot=!1,this.labelId=nextId("graph-query-builder-label"),this.hintId=nextId("graph-query-builder-hint"),this.errorId=nextId("graph-query-builder-error"),this._fieldsetDisabled=!1,this._name="",this._value=EMPTY_VALUE,this.defaultValue=normalizeGraphQuery(EMPTY_VALUE),this.defaultValueCaptured=!1,this._disabled=!1,this.hasInteracted=!1,this.removalFocusGeneration=0,this.onChromeSlotChange=event=>{const slot=event.currentTarget,hasContent=slot.assignedNodes({flatten:!0}).some(node=>node.nodeType===Node.TEXT_NODE?!!node.textContent?.trim():!0);slot.name==="hint"?this.hasHintSlot=hasContent:slot.name==="error"&&(this.hasErrorSlot=hasContent)},this.internals=attachInternalsSafely(this),this.validityController=new AnchoredValidityController(this,this.internals,()=>this[VALIDITY_ANCHOR]()),installCustomErrorProperty(this,()=>this.validityController.customValidityMessage),installInvalidEventAlias(this,init=>this.emit("lr-invalid",null,init)),this.syncFormState()}disconnectedCallback(){this.removalFocusGeneration++,this.pendingRemovalFocus=void 0,super.disconnectedCallback()}get form(){return getFormOwner(this.internals)}set form(owner){setFormOwner(this,owner)}getForm(){return getFormOwner(this.internals)}get labels(){return this.internals.labels}get validity(){return this.internals.validity}get validationMessage(){return this.internals.validationMessage}get willValidate(){return this.internals.willValidate}get value(){return this._value}set value(next){const old=this._value;this._value=normalizeGraphQuery(next),this.syncFormState(),this.requestUpdate("value",old)}get name(){return this._name}set name(next){const old=this._name;this._name=next??"",this._name?this.setAttribute("name",this._name):this.removeAttribute("name"),this.requestUpdate("name",old)}get disabled(){return this._disabled}set disabled(next){const old=this._disabled;this._disabled=!!next,this.toggleAttribute("disabled",this._disabled),this.validityController&&this.syncFormState(),this.requestUpdate("disabled",old)}get effectiveDisabled(){return this.disabled||this._fieldsetDisabled}get errors(){return this.publicValidityErrors()}publicValidityErrors(){const errors={...this._errors};return this.willValidate&&this.validity.customError&&(errors.base=this.validationMessage),Object.freeze(errors)}publishValiditySnapshot(){if(!this.isConnected)return;const valid=!this.willValidate||this.validity.valid,errors=valid?Object.freeze({}):this.publicValidityErrors(),key=JSON.stringify({valid,errors});key!==this.lastValidityKey&&(this.lastValidityKey=key,this.emit("lr-validity-change",Object.freeze({valid,errors})))}[VALIDITY_ANCHOR](){const firstInvalidPart=Object.keys(this._errors)[0];if(!(!firstInvalidPart||!this.renderRoot))return this.renderRoot.querySelector(`[part="${firstInvalidPart}"]`)??void 0}computeValidation(){const errors={},flags={};return this._value.startId.trim()||(errors["start-input"]=this.localize("fieldRequired"),flags.valueMissing=!0),this._value.minHops>this._value.maxHops&&(errors["max-hops"]=this.localize("graphQueryHopRangeInvalid"),flags.rangeUnderflow=!0),{errors,flags}}syncFormState(){const{errors,flags}=this.computeValidation();this._errors=errors;let formValue=null;try{formValue=JSON.stringify(this._value)}catch{formValue=null}if(this.internals.setFormValue(formValue,formValue),this.barredFromValidation||Object.keys(flags).length===0)this.validityController.setValidity({});else{const message=Object.values(errors)[0]??"";this.validityController.setValidity(flags,message)}this.syncValidityCustomStates(),this.publishValiditySnapshot()}get barredFromValidation(){return isBarredFromValidation(this,this.internals)}syncValidityCustomStates(){syncValidityStates(this.internals,{required:!0,hasInteracted:this.hasInteracted,barred:this.barredFromValidation})}checkValidity(){return this.syncFormState(),this.internals.checkValidity()}reportValidity(){return this.hasInteracted=!0,this.syncFormState(),Object.keys(this._errors).length>0&&(this.touchedFields=new Set([...this.touchedFields,...Object.keys(this._errors)])),this.internals.reportValidity()}setCustomValidity(message){this.validityController.setCustomValidity(message??""),this.syncValidityCustomStates(),this.publishValiditySnapshot()}formResetCallback(){this.hasInteracted=!1,this.captureDefaultValue(),this.value=this.defaultValue,this.touchedFields=new Set,this.saveName=""}captureDefaultValue(){this.defaultValueCaptured||(this.defaultValue=normalizeGraphQuery(this._value),this.defaultValueCaptured=!0)}formStateRestoreCallback(state2,_mode){let restored=EMPTY_VALUE;if(typeof state2=="string")try{const parsed=JSON.parse(state2);parsed!==null&&typeof parsed=="object"&&!Array.isArray(parsed)&&(restored=normalizeGraphQuery(parsed))}catch{}this.value=restored}formDisabledCallback(disabled){this._fieldsetDisabled=disabled,this.syncFormState(),this.requestUpdate()}get liveDisabled(){return this.effectiveDisabled||this.matches(":disabled")}focusFirstControl(options){if(!this.renderRoot||this.liveDisabled)return;(this.renderRoot.querySelector('[part="start-input"]')||this.renderRoot.querySelector('[part="end-input"]')||this.renderRoot.querySelector('[part="min-hops"]')||this.renderRoot.querySelector('[part="max-hops"]')||this.renderRoot.querySelector('[part="direction"]')||this.renderRoot.querySelector('[part="save-name-input"]'))?.focus(options)}focus(options){this.focusFirstControl(options)}blur(){const active=deepActiveElementIn(this.shadowRoot);active&&typeof active.blur=="function"&&active.blur()}click(){this.focusFirstControl()}setValue(next){this.effectiveDisabled||(this.hasInteracted=!0,this.value=next,this.emit("lr-input",Object.freeze({value:this._value})))}addRelationshipType(type){!type||this._value.relationshipTypes.includes(type)||this.setValue({...this._value,relationshipTypes:[...this._value.relationshipTypes,type]})}removeRelationshipType(type){this.captureChipRemovalFocus("relationship",type,this._value.relationshipTypes),this.setValue({...this._value,relationshipTypes:this._value.relationshipTypes.filter(t=>t!==type)})}addNodeType(type){!type||this._value.nodeTypes.includes(type)||this.setValue({...this._value,nodeTypes:[...this._value.nodeTypes,type]})}removeNodeType(type){this.captureChipRemovalFocus("node-type",type,this._value.nodeTypes),this.setValue({...this._value,nodeTypes:this._value.nodeTypes.filter(t=>t!==type)})}captureChipRemovalFocus(group,value,selected){const active=this.shadowRoot?.activeElement,expectedPart=group==="relationship"?"relationship-chips":"node-type-chips";if(active?.localName!=="lr-chip"||active.getAttribute("value")!==value||active.closest("lr-chip-group")?.getAttribute("part")!==expectedPart)return;const index=selected.indexOf(value),survivors=selected.filter(candidate=>candidate!==value),targetValue=survivors[Math.min(Math.max(index,0),survivors.length-1)];this.pendingRemovalFocus={kind:"chip",group,targetValue},this.removalFocusGeneration++}markTouched(part){this.hasInteracted=!0,this.syncValidityCustomStates(),!this.touchedFields.has(part)&&(this.touchedFields=new Set(this.touchedFields).add(part))}runQuery(){if(this.effectiveDisabled||!this.reportValidity())return;const detail=()=>Object.freeze({query:normalizeGraphQuery(this._value)});this.emit("lr-before-query-run",detail(),{cancelable:!0}).defaultPrevented||this.emit("lr-query-run",detail())}saveQuery(){if(this.effectiveDisabled)return;const name=this.saveName.trim();if(!name)return;const detail=()=>Object.freeze({name,query:normalizeGraphQuery(this._value)});this.emit("lr-before-query-save",detail(),{cancelable:!0}).defaultPrevented||(this.saveName="",this.emit("lr-query-save",detail()))}loadQuery(item){if(this.effectiveDisabled)return;const detail=()=>Object.freeze({queryId:item.id,query:normalizeGraphQuery(item.query)});this.emit("lr-before-query-load",detail(),{cancelable:!0}).defaultPrevented||(this.setValue({...EMPTY_VALUE,...item.query}),this.emit("lr-query-load",detail()))}deleteQuery(item){if(this.effectiveDisabled)return;const detail=()=>Object.freeze({queryId:item.id});this.emit("lr-before-query-delete",detail(),{cancelable:!0}).defaultPrevented||this.emit("lr-query-delete",detail())}willUpdate(changed){if(super.willUpdate(changed),this.hasUpdated||this.captureDefaultValue(),!changed.has("savedQueries"))return;const active=this.shadowRoot?.activeElement;if(active?.getAttribute("part")!=="saved-delete-button")return;const focusedId=active.closest("[data-query-id]")?.dataset.queryId;if(!focusedId||this.savedQueries.some(item=>item.id===focusedId))return;const index=(changed.get("savedQueries")??[]).findIndex(item=>item.id===focusedId),target=this.savedQueries[Math.min(Math.max(index,0),this.savedQueries.length-1)];this.pendingRemovalFocus={kind:"saved",targetId:target?.id},this.removalFocusGeneration++}updated(changed){super.updated(changed),this.publishValiditySnapshot();const pending=this.pendingRemovalFocus;if(!pending)return;this.pendingRemovalFocus=void 0;const generation=this.removalFocusGeneration;this.scheduleAfterUpdate(()=>{if(!(generation!==this.removalFocusGeneration||!this.isConnected)){if(pending.kind==="chip"){if(pending.targetValue){const part=pending.group==="relationship"?"relationship-chips":"node-type-chips",chip=[...this.shadowRoot?.querySelectorAll(`[part="${part}"] lr-chip`)??[]].find(candidate=>candidate.getAttribute("value")===pending.targetValue);if(chip){chip.focus();return}}const pickerPart=pending.group==="relationship"?"relationship-picker":"node-type-picker";this.shadowRoot?.querySelector(`[part="${pickerPart}"]`)?.focus();return}if(pending.targetId){const action=[...this.shadowRoot?.querySelectorAll("[data-query-id]")??[]].find(candidate=>candidate.dataset.queryId===pending.targetId)?.querySelector('[part="saved-delete-button"]');if(action){action.focus();return}}this.shadowRoot?.querySelector('[part="save-name-input"]')?.focus()}},"graph-query-removal-focus")}hopOptions(){const limit=finiteInteger(this.hopLimit,6,1,20),options=new Set(Array.from({length:limit},(_,i)=>i+1));return options.add(this._value.minHops),options.add(this._value.maxHops),[...options].sort((a,b)=>a-b)}labelForType(options,value){return options.find(o=>o.value===value)?.label??value}renderTypeFilter(kind,options,selected,add,remove,disabled){const pickerPart=kind==="relationship"?"relationship-picker":"node-type-picker",chipsPart=kind==="relationship"?"relationship-chips":"node-type-chips",pickerLabel=kind==="relationship"?this.localize("graphQueryRelationshipTypeLabel"):this.localize("graphQueryNodeTypeLabel"),available=options.filter(o=>!selected.includes(o.value));return html`
       <div part="filter-group" data-kind=${kind}>
         <lr-select
           part=${pickerPart}

package/dist/components/data/heatmap/heatmap.class.d.ts

@@ -1,6 +1,18 @@
 import { type PropertyValues, type TemplateResult } from 'lit';
 import { LyraElement } from '../../../internal/lyra-element.js';
 import { type CalendarDay } from './calendar-grid.js';
+/**
+ * Which matrix label band, if any, is frozen while the grid scrolls.
+ *
+ * One closed set rather than a boolean or a pair of booleans, because freezing one axis is a real
+ * request on its own: a wide matrix needs the row gutter to survive horizontal scrolling, a tall one
+ * needs the column band to survive vertical scrolling, and the two are independent. A boolean cannot
+ * express that at all, and a `sticky-row-labels`/`sticky-col-labels` pair spends two attributes and
+ * four states on it while leaving no single reflected value to select on in CSS. The `rows`/`cols`
+ * spelling matches the vocabulary the rest of this component already uses (`rowLabels`,
+ * `row-label-width`, `colLabels`, `col-label-height`) rather than introducing axis letters.
+ */
+export type LyraHeatmapStickyLabels = 'none' | 'rows' | 'cols' | 'both';
 /**
  * A linear RGB ramp cannot contain more than 256 visually distinct integer
  * steps on any channel. Keeping the bucket count within that bound avoids an
@@ -88,6 +100,14 @@ export interface HeatmapLegendStop {
     color?: string;
     /** Optional label override; defaults to the component's own numeric formatting of `value`. */
     label?: string;
+    /**
+     * Set to `false` to exclude this stop from `warnOnLegendRampMismatch()`'s `colorSteps` agreement
+     * check, for a real, distinctly-colored swatch that is intentionally not part of the sequential
+     * ramp -- e.g. a calendar heatmap's fixed neutral "no data" color shown alongside an N-step
+     * ramp. Defaults to `true`. A caption-only stop (no `color`) is already excluded regardless of
+     * this flag, since it describes no color to compare.
+     */
+    partOfRamp?: boolean;
 }
 /** A single cell to mark as persistently selected -- `row`/`col` in matrix mode, `date` in
  *  calendar mode (whichever pair matches the active `mode`; the other field is ignored),
@@ -139,8 +159,14 @@ export type LyraHeatmapCellClickDetail = {
     col: number;
     value: number;
 };
+export type LyraHeatmapMatrixGeometryChangeDetail = {
+    padLeft: number;
+    padTop: number;
+    cellSize: number;
+};
 export interface LyraHeatmapEventMap {
     'lr-cell-click': CustomEvent<LyraHeatmapCellClickDetail>;
+    'lr-matrix-geometry-change': CustomEvent<LyraHeatmapMatrixGeometryChangeDetail>;
 }
 /**
  * `<lr-heatmap>` — a Canvas heatmap with a DPR-aware, resize-aware redraw
@@ -213,6 +239,22 @@ export interface LyraHeatmapEventMap {
  * focus, its semantic matrix coordinate or calendar date remains the sole roving stop; removal
  * clamps to the nearest survivor, or to the stable heatmap base when no interactive cells remain.
  *
+ * `stickyLabels` freezes a matrix label band against the grid's own scrolling — `'rows'` pins the
+ * row-label gutter through horizontal scrolling, `'cols'` pins the column-label band through
+ * vertical scrolling, `'both'` pins both. The frozen band is repainted into its own layer from the
+ * same `matrixGeometry` the cells were painted with in the same pass, so it tracks a
+ * `row-label-width`/`col-label-height` `"auto"` re-resolution instead of hardcoding it. The default
+ * `'none'` renders exactly what it always did: one canvas, no scrollport.
+ *
+ * Everything positioned in canvas coordinates moves into that scrollport with the cells. The hover
+ * tooltip renders inside it, so it stays on the cell it describes through a scroll instead of
+ * drifting by the scroll offset; since `overflow: auto` there clips whatever leaves the
+ * scrollport, it is also kept inside the visible window — clamped along the inline axis, and
+ * flipped to below its cell when a frozen band leaves no room above. Arrow-key navigation scrolls
+ * the focused cell into that window, clear of the frozen bands: the canvas is the roving tab stop,
+ * its focus ring is painted into the bitmap, and it calls `preventDefault()` on the arrows, so
+ * without that scroll a keyboard user has no way at all to bring the focused cell back into view.
+ *
  * Calendar `data.columnX` overrides the x-origin computed for each
  * week column — drawing, hit-testing, the focus ring, and month-label
  * positioning all consult it consistently, so a consumer can pixel-align a
@@ -251,11 +293,20 @@ export interface LyraHeatmapEventMap {
  * tooltip and the keyboard live-region announcement. Use the callback for application-specific
  * wording that is not represented by the locale catalog.
  * `cellColor` overrides a cell's ramp-computed color entirely for an exact value.
+ * @event lr-matrix-geometry-change - Fired after a matrix-mode draw pass whose resolved
+ * `matrixGeometry` (`padLeft`/`padTop`/`cellSize`) differs from the previous draw -- e.g. after
+ * `row-label-width="auto"`/`col-label-height="auto"` resolves against new label content or a
+ * resize. `detail` is the same object `matrixGeometry` returns. Never fired in calendar mode.
  * @csspart base - The heatmap wrapper.
  * @csspart canvas - The heatmap canvas.
+ * @csspart grid - The scrollport wrapping the canvas while `stickyLabels` freezes an axis; absent otherwise.
+ * @csspart row-labels - The frozen row-label gutter, rendered while `stickyLabels` is `rows` or `both`.
+ * @csspart col-labels - The frozen column-label band, rendered while `stickyLabels` is `cols` or `both`.
  * @csspart cells - The opt-in per-cell accessibility overlay.
  * @csspart cell - An opt-in native button for one matrix or calendar cell.
- * @csspart tooltip - The hover tooltip.
+ * @csspart tooltip - The hover tooltip, positioned over the hovered cell. It renders inside
+ *   `[part="grid"]` while `stickyLabels` freezes an axis (so it scrolls with the cells) and as a
+ *   `[part="base"]` child otherwise.
  * @csspart live-region - An aria-hidden shadow mirror of the keyboard announcement; the actual
  *   announcement uses the shared light-DOM polite sink.
  * @csspart projection-limit - Localized assistive disclosure for bounded projections.
@@ -276,6 +327,8 @@ export interface LyraHeatmapEventMap {
  * @cssprop [--lr-heatmap-focus-ring-color=var(--lr-focus-ring-color)] - Focus ring around a focused cell.
  * @cssprop [--lr-heatmap-annotation-color=var(--lr-color-danger)] - Border color for an annotated cell.
  * @cssprop [--lr-heatmap-selected-color=var(--lr-color-success)] - Border color for the selected cell.
+ * @cssprop [--lr-heatmap-sticky-label-bg=var(--lr-color-surface)] - Backdrop painted under a frozen `stickyLabels` band. Must be opaque: it covers the same labels the scrolling canvas painted underneath it.
+ * @cssprop [--lr-heatmap-grid-max-block-size=none] - Block-size ceiling of the `stickyLabels` scrollport. A frozen column band only stays behind once the grid actually scrolls vertically.
  * @cssprop [--lr-heatmap-color-steps-gradient=linear-gradient(to right, var(--lr-heatmap-scale-lo), var(--lr-heatmap-scale-hi))] - Gradient painted on the continuous legend bar. Set on the host by the component itself while `colorSteps` is supplied, and removed again when it is not; the fallback is the two-endpoint scale ramp.
  * @status stable
  * @since 4.0.0
@@ -339,6 +392,46 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      * would be incoherent.
      */
     colLabelRotation?: number;
+    private _stickyLabels;
+    /**
+     * Freezes a matrix label band against the grid's own scrolling, instead of leaving it baked into
+     * the scrolling bitmap. `'rows'` pins the row-label gutter so it survives horizontal scrolling,
+     * `'cols'` pins the column-label band so it survives vertical scrolling, `'both'` pins both, and
+     * the default `'none'` renders exactly what this component rendered before the option existed:
+     * one canvas, no scrollport, no extra elements.
+     *
+     * Labels and cells share one bitmap, so a band cannot be `position: sticky` on its own; a tall
+     * matrix therefore scrolled its column header away and left the columns unidentifiable. Setting
+     * this repaints the requested band into its own layer, in the same draw pass and from the same
+     * resolved `matrixGeometry` the cells were painted with, so the two cannot drift under scroll, a
+     * resize, a DPR change, or a `rowLabelWidth`/`colLabelHeight` `"auto"` re-resolution. That last
+     * one is the point: a hand-rolled light-DOM mirror had to hardcode the gutter width, which made
+     * it mutually exclusive with `row-label-width="auto"`.
+     *
+     * Freezing needs something to scroll, so the frozen modes wrap the grid in a `[part="grid"]`
+     * scrollport. It is bounded inline by the host's own allocation (a matrix wider than a 320px host
+     * scrolls inside the component rather than overflowing it) and unbounded in block by default; set
+     * `--lr-heatmap-grid-max-block-size` to bound it, since a column band can only stay behind while
+     * the grid actually scrolls vertically.
+     *
+     * Matrix mode only, like `matrixGeometry` and `lr-matrix-geometry-change`: calendar mode's axes
+     * are a different geometry (a fixed weekday gutter, a month band, and the optional `columnX`/
+     * `rowY` overrides), so this property is read but has no effect there.
+     *
+     * Under `dir="rtl"` the grid keeps this component's documented physical LTR geometry, so the
+     * scrollport is direction-pinned like the canvas already is and the bands then freeze against the
+     * logical inline-start/block-start edges of that pinned box — which is to say the physical left
+     * and top, where the labels they duplicate are actually painted.
+     *
+     * See `LyraHeatmapStickyLabels` for why this is one closed set rather than a boolean or a pair.
+     */
+    get stickyLabels(): LyraHeatmapStickyLabels;
+    set stickyLabels(next: LyraHeatmapStickyLabels);
+    /** `stickyLabels` restricted to the mode it applies to. One gate for render and paint alike, so
+     *  switching `data` to a calendar can never leave a frozen band or a scrollport behind. */
+    private get effectiveStickyLabels();
+    private get freezesRowLabels();
+    private get freezesColLabels();
     /** Column band resolved during the last draw, mirroring `resolvedRowLabelWidth`. */
     private resolvedColLabelHeight;
     /** Normalized rotation in degrees: finite, clamped to `[0, 90]`. */
@@ -347,6 +440,31 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      *  painted. Only ever differs from the default while `rowLabelWidth="auto"`. */
     private resolvedRowLabelWidth;
     private get matrixPadLeft();
+    /**
+     * The gutter/cell geometry the last matrix-mode draw actually painted with --
+     * `{ padLeft, padTop, cellSize }`, all in CSS pixels -- so a light-DOM consumer (e.g. a sticky
+     * header mirror) can line up with the canvas without hardcoding the same numbers `row-label-width`
+     * or `col-label-height`'s `"auto"` resolution would otherwise keep private. `undefined` in
+     * calendar mode, and before the first matrix draw.
+     *
+     * This returns the frozen object `drawMatrix()` stored (and `lr-matrix-geometry-change` carried)
+     * on the last draw -- not a fresh computation. That distinction is the whole contract. Computing
+     * it on read from the same internal getters `drawMatrix()` uses looks equivalent and is not:
+     * those getters read CURRENT layout, so any interval where layout has moved but no draw has
+     * happened yet makes the getter describe a canvas that does not exist. Two such intervals are
+     * routine -- full redraws pause while the host is outside the viewport (documented behaviour of
+     * this component), and `rowLabelWidth`/`colLabelHeight` are not redraw-triggering properties at
+     * all -- and both land hardest on the tall, partly-scrolled matrix this getter exists to serve.
+     * Returning the stored object also makes the getter and the event the same value by
+     * construction rather than by coincidence.
+     */
+    get matrixGeometry(): Readonly<LyraHeatmapMatrixGeometryChangeDetail> | undefined;
+    /** The geometry the last `drawMatrix()` pass painted with, frozen and shared with the
+     *  `lr-matrix-geometry-change` detail. `undefined` until the first draw, which is what gates
+     *  `matrixGeometry` returning a real value only once there is a draw to describe. Also backs the
+     *  event's change detection, so a same-valued redraw (a color-only update, an unrelated data
+     *  change) does not refire it. */
+    private lastPaintedMatrixGeometry?;
     private get matrixPadTop();
     /** Tallest rotated column label plus inset, floored at the built-in band and capped so labels can
      *  never crowd out the matrix. The column mirror of `measureRowLabelWidth()`. */
@@ -644,7 +762,8 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      * Warning rather than deriving one from the other: deriving would silently change what an
      * existing `colorSteps`-only consumer sees, and would also break the deliberate `cellColor`
      * escape hatch. This keeps every current behavior and only makes the disagreement audible.
-     * Compares only the stops that carry a color -- a caption-only stop describes no color at all.
+     * Compares only the stops that carry a color -- a caption-only stop describes no color at all --
+     * and, among those, only the ones that did not opt out via `partOfRamp: false`.
      */
     private warnOnLegendRampMismatch;
     private cachedLegendStops;
@@ -733,6 +852,10 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
     private labelColor;
     /** Reads the customizable canvas axis/label font off the host's computed style. */
     private labelFont;
+    /** Reads the customizable frozen-label-band backdrop off the host's computed style, resolved to a
+     *  concrete color: canvas silently keeps its previous `fillStyle` for anything it cannot parse,
+     *  and a `var()` chain is exactly that. */
+    private stickyLabelBg;
     /** Reads the customizable no-data cell fill off the host's computed style. */
     private noDataFill;
     /** Reads the customizable canvas-drawn keyboard-focus-ring stroke color off the host's computed style. */
@@ -863,6 +986,32 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
     private paintCalendarFocusOverlays;
     private repaintCalendarFocusCell;
     private drawMatrix;
+    /** Paints the row-label gutter at `x = 0 .. padLeft`. Extracted so the cell canvas and a frozen
+     *  `[part="row-labels"]` band paint from one routine and one set of geometry arguments — the
+     *  band's own canvas shares the cell canvas's origin, so "aligned" is what the same coordinates
+     *  mean, rather than something a second implementation has to keep agreeing about. */
+    private paintMatrixRowLabels;
+    /** The column-label band at `y = 0 .. padTop`, rotation included. The mirror of
+     *  `paintMatrixRowLabels()`, shared with a frozen `[part="col-labels"]` band the same way. */
+    private paintMatrixColLabels;
+    /**
+     * Repaints whichever label bands `stickyLabels` freezes, from the geometry this very draw pass
+     * painted the cells with. Each band is a canvas sharing the cell canvas's origin (both sit in the
+     * same single-area grid), sized to the band it owns and offset on one axis only by
+     * `position: sticky`, so it slides along the axis it is not frozen on and stays put on the one it
+     * is. Nothing here recomputes geometry, which is what keeps a band aligned across a resize, a DPR
+     * change, and a `row-label-width`/`col-label-height` `"auto"` re-resolution alike.
+     *
+     * The cell canvas keeps painting its own labels underneath: leaving that pass untouched is what
+     * makes the default `'none'` byte-identical, and the band's opaque backdrop covers the duplicate
+     * once it scrolls out from under the frozen copy.
+     */
+    private paintFrozenLabelBands;
+    private frozenBandCanvas;
+    /** Sizes one band's backing store to the same DPR the cell canvas uses, fills the opaque backdrop,
+     *  then hands the caller a context already in CSS-pixel coordinates identical to the cell
+     *  canvas's — so a label lands on the same physical pixel in both. */
+    private paintFrozenBand;
     /**
      * Maps a pointer position, in canvas-local CSS px (e.g.
      * `PointerEvent.offsetX/offsetY`), to the cell underneath it — or `null`
@@ -905,7 +1054,7 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      *  `CalendarCellPos` in this component goes through here, so no call site can forget the date. */
     private calendarPos;
     /**
-     * Pixel rect (canvas-local CSS px) of a cell — shared by `tooltipStyle()`
+     * Pixel rect (canvas-local CSS px) of a cell — shared by `tooltipAnchor()`
      * so the tooltip's position always agrees with the same geometry
      * `drawMatrix()`/`drawCalendar()`/`hitTest*()` use.
      */
@@ -933,8 +1082,53 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      *  wording anywhere around the cell text instead of it being appended. */
     private announce;
     private emitCellClick;
-    /** Inline `style` for `[part="tooltip"]`, centered above the given cell. */
-    private tooltipStyle;
+    /** The `stickyLabels` scrollport, or `null` in the default unfrozen render, which has none. */
+    private get gridScrollport();
+    /** The tooltip's own rendered box in CSS px, recorded by `measureTooltip()`: `inline` is its
+     *  border box, `block` that box plus the token-sized gap it keeps from the cell. Only read while
+     *  a scrollport can clip it; zero until the first measurement, which degrades to the unclamped
+     *  placement rather than to a wrong one. */
+    private tooltipSize;
+    /**
+     * Records the tooltip's rendered size, so the next paint can keep it inside the `stickyLabels`
+     * scrollport. Measured rather than derived: the box is sized by caller text, and the gap it
+     * keeps from the cell is a design token whose value belongs in the stylesheet.
+     *
+     * Repositioning can never resize it (`white-space: nowrap`, no inline-size constraint), so the
+     * re-render scheduled here always settles in one step. It runs from `scheduleAfterUpdate()`
+     * rather than straight out of `updated()` on purpose: that keeps the `requestUpdate()` outside
+     * Lit's own update cycle, and its microtask still flushes before paint, so the corrected
+     * position is the first one the user ever sees.
+     */
+    private measureTooltip;
+    /**
+     * Inline `style` for `[part="tooltip"]` — centered on the given cell — plus whether it had to be
+     * flipped below that cell.
+     *
+     * With no `stickyLabels` scrollport this is the original unconditional "centered above the cell"
+     * placement, in the canvas-local coordinates `cellRect()` returns. With one, the tooltip renders
+     * *inside* that scrollport, which is what keeps it pinned to the cell it describes through a
+     * scroll — and there `overflow: auto` clips whatever leaves the scrollport, while an opaque
+     * frozen band hides whatever is drawn under it. So the placement is additionally kept inside the
+     * band-free part of the visible window: still centered on the cell but clamped to that window,
+     * and flipped to below the cell when there is no room above it and there is room below. Flipping
+     * is conditional on both, deliberately: an unconditional flip at the block end would push the
+     * tooltip past the content box and grow the scrollable area under the pointer.
+     */
+    private tooltipAnchor;
+    /**
+     * Keeps the keyboard-focused cell inside the `stickyLabels` scrollport, clear of the frozen
+     * bands' own boxes.
+     *
+     * Without this the feature is an accessibility regression: the default (unset `accessibleCells`)
+     * roving stop is the canvas itself, its focus ring is painted into the canvas bitmap rather than
+     * carried by a focusable element the browser would scroll to, and `onMatrixKeyDown()` calls
+     * `preventDefault()` on every arrow — so the browser's own scrolling never happens either, and
+     * arrowing far enough leaves the focus indicator off-screen with no keyboard way to reveal it.
+     * A minimal scroll (never re-centering a cell that is already fully visible) keeps the scroll
+     * position stable while arrowing around inside the visible window.
+     */
+    private scrollCellIntoView;
     /**
      * Value-equality check for a `CellPos`, since `hoverCell` is assigned a
      * fresh object literal on every `pointermove` — Lit's `@state()`
@@ -981,6 +1175,29 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      * unset (or empty) `legendStops` therefore reproduces the pre-`legendStops` markup exactly.
      */
     private renderLegendScale;
+    /**
+     * The cell canvas, the opt-in per-cell overlay, and — while `stickyLabels` freezes an axis — the
+     * frozen label bands, wrapped in the scrollport those bands stick to.
+     *
+     * Both branches emit the same canvas and overlay from one template, so the unfrozen default keeps
+     * rendering exactly the elements it always did (no wrapper, no scrollport, no second canvas) with
+     * no second copy of the canvas's attribute/listener surface to drift. The bands are decorative
+     * duplicates of pixels the cell canvas already painted, so they carry `aria-hidden` and no role:
+     * the accessible representation stays the canvas's own `role="application"` name, or the
+     * `[part="cells"]` grid under `accessibleCells` — which moves inside the scrollport so the cells
+     * scroll with the canvas they overlay.
+     */
+    private renderGridSurface;
+    /**
+     * The hover tooltip, rendered once: inside the `stickyLabels` scrollport's stack when an axis is
+     * frozen (see `renderGridSurface()`), and as the `[part="base"]` sibling it has always been
+     * otherwise, where the canvas's origin already *is* the base's.
+     *
+     * `dir` is carried explicitly because the scrollport pins `direction: ltr` for the physically
+     * non-mirrored grid geometry, and the tooltip is the one thing in there that is prose rather
+     * than geometry -- it keeps the host's own direction it inherited before the scrollport existed.
+     */
+    private renderTooltip;
     render(): TemplateResult;
     /** `localize()` interpolates with a bare `String(value)`, so a number handed to it renders in
      *  ASCII digits no matter the locale -- mixing two numbering systems inside one translated