Component Metadata

Static component behavior is authored with ordinary top-level assignments. Lit^sx carries these assignments onto the generated custom-element class.

import { css } from "@litsx/core";

export function DialogPanel({ open = false }) {
  return <dialog open={open}><slot /></dialog>;
}

DialogPanel.styles = css`:host { display: contents; }`;
DialogPanel.properties = { open: { type: Boolean, reflect: true } };
DialogPanel.shadowRootOptions = { mode: "open", delegatesFocus: true };

Component names

A component identifier must derive directly to a valid custom-element name. Use at least two words: DialogPanel maps to dialog-panel, while a single-word identifier such as Dialog is rejected. Lit^sx does not invent framework prefixes or suffixes.

Namespace members are also explicit: Controls.Switch maps to controls-switch. This keeps generated tag names stable and visible in authored code.

Supported metadata

• Component.styles owns static Lit styles. It accepts a CSSResult or a nested array of CSSResult values, applied in order. Import css from @litsx/core; see Styling for composition and inherited-style behavior.
• Component.properties refines inferred Lit property descriptors.
• Component.shadowRootOptions configures the shadow root.
• Component.elements supplies scoped custom-element constructors.
• Component.lightDom = true renders the component into its host.
• other ordinary static assignments are retained when the generated class or an integration consumes them.

Assignments must be at module scope after the component is declared. They are standard JavaScript/TypeScript, so normal editor navigation, formatting, and static analysis apply.

Light DOM

export function PageSection({ children }) {
  return <section>{children}</section>;
}

PageSection.lightDom = true;
PageSection.styles = css`section { container-type: inline-size; }`;

CSS integrations that generate Light DOM styles can use lightDomStyles: "scoped" | "global" | "none" to select their routing strategy. In integrations that use the default scoped route, each component receives a stable boundary. This option does not select a CSS engine and does not replace authored Component.styles.

Scoped elements

import { CompactAvatar } from "./compact-avatar.tsx";

export function UserCard({ user }) {
  return <CompactAvatar user={user} />;
}

UserCard.elements = { CompactAvatar };

The compiler normally generates scoped-element metadata for imported component use. Explicit elements metadata is useful when a library or advanced composition pattern owns the registry mapping.

Static methods

Expose class-level behavior with ordinary assignments:

export function StatusBadge({ tone }) {
  return <span data-tone={tone}><slot /></span>;
}

StatusBadge.canHandle = (tone) => tone === "success" || tone === "warning";

This is separate from useExpose(...), which publishes an instance-level imperative handle through a ref.