@esphome/compose-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xmlguy74
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,541 @@
+import * as _esphome_compose from '@esphome/compose';
+import { EspComposeElement } from '@esphome/compose';
+
+/**
+ * Theme type definitions for the LVGL design system.
+ *
+ * A Theme is a compile-time configuration object that drives all visual
+ * token resolution in design system components.  Third parties can create
+ * custom themes by implementing this interface.
+ */
+type SpacingToken = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type SizeToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type RadiusToken = 'none' | 'sm' | 'md' | 'lg' | 'full';
+type StatusToken = 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+type TextVariant = 'title' | 'subtitle' | 'body' | 'caption';
+interface FontDef {
+    /** Font family name (e.g. 'montserrat'). */
+    fontFamily: string;
+    /** Font size in pixels (e.g. 28). Resolved to `{fontFamily}_{fontSize}` for LVGL. */
+    fontSize: number;
+}
+interface SizeDimensions {
+    height: number;
+    fontSize: number;
+    paddingX: number;
+    paddingY: number;
+}
+interface StatusColors {
+    bg: string;
+    text: string;
+    bgPressed: string;
+}
+interface ThemeColors {
+    primary: StatusColors;
+    secondary: StatusColors;
+    success: StatusColors;
+    warning: StatusColors;
+    danger: StatusColors;
+    background: string;
+    surface: string;
+    surfaceAlt: string;
+    border: string;
+    textPrimary: string;
+    textSecondary: string;
+    textDisabled: string;
+}
+interface ThemeTypography {
+    title: FontDef;
+    subtitle: FontDef;
+    body: FontDef;
+    caption: FontDef;
+}
+interface Theme {
+    /** Human-readable theme name. */
+    name: string;
+    /** Color palette. */
+    colors: ThemeColors;
+    /** Typography scale. */
+    typography: ThemeTypography;
+    /** Spacing scale in pixels. */
+    spacing: Record<SpacingToken, number>;
+    /** Border radius scale in pixels. */
+    radii: Record<RadiusToken, number>;
+    /** Component size scale. */
+    sizes: Record<SizeToken, SizeDimensions>;
+}
+
+/** The theme context — defaults to `darkTheme` when no provider is present. */
+declare const ThemeContext: _esphome_compose.Context<Theme>;
+/** Read the active theme from the nearest `<ThemeProvider>`. */
+declare function useTheme(): Theme;
+/**
+ * Provide a theme to all descendant design-system components.
+ *
+ * @example
+ * <ThemeProvider value={lightTheme}>
+ *   <Screen padding="lg">…</Screen>
+ * </ThemeProvider>
+ */
+declare const ThemeProvider: (props: {
+    value: Theme;
+    children?: _esphome_compose.EspComposeElement | _esphome_compose.EspComposeElement[];
+}) => _esphome_compose.EspComposeElement;
+
+/**
+ * Default dark theme — designed for LVGL embedded displays.
+ *
+ * Optimised for small screens: high contrast, saturated accents,
+ * dark surfaces that reduce power on OLED and improve readability
+ * in varying ambient light.
+ */
+
+declare const darkTheme: Theme;
+
+/**
+ * Built-in light theme — designed for LVGL embedded displays.
+ *
+ * Light surfaces with dark text, suitable for well-lit environments.
+ * Shares spacing, radii and typography scale with the dark theme.
+ */
+
+declare const lightTheme: Theme;
+
+/**
+ * JSON theme import / export for interop.
+ */
+
+/** Serialise a Theme to a JSON string. */
+declare function themeToJSON(theme: Theme): string;
+/** Parse a JSON string into a Theme object. */
+declare function themeFromJSON(json: string): Theme;
+
+/**
+ * Theme-aware token resolvers.
+ *
+ * All resolvers read from the active theme (set via `setTheme()`).
+ * Component code calls these instead of accessing tokens directly.
+ */
+
+/** Resolve a spacing token or pass through a raw pixel value. */
+declare function resolveSpacing(value: SpacingToken | number): number;
+/** Resolve a component size token. */
+declare function resolveSize(value: SizeToken): SizeDimensions;
+/** Resolve a status color token. */
+declare function resolveStatus(value: StatusToken): StatusColors;
+/** Resolve a typography variant to a font definition. */
+declare function resolveTypography(variant: TextVariant): FontDef;
+/** Convert a `FontDef` to the LVGL `text_font` string (e.g. `montserrat_28`). */
+declare function fontDefToLvgl(def: FontDef): string;
+/** Resolve a radius token or pass through a raw pixel value. */
+declare function resolveRadius(value: RadiusToken | number): number;
+
+/**
+ * Intent constants for @esphome/compose-ui design system.
+ *
+ * These are owned by the UI package — the base SDK is unaware of them.
+ * Most DS components declare only `lvgl:widget` for LVGL container placement.
+ * These two intents enforce strict parent-child pairing.
+ */
+/** Design system intents — structural parent-child constraints. */
+declare const COMPOSE_UI_INTENTS: {
+    /** Col can only be placed inside Row. */
+    readonly COL: "compose-ui:col";
+    /** GridItem can only be placed inside Grid. */
+    readonly GRID_ITEM: "compose-ui:grid-item";
+};
+
+interface ScreenProps {
+    children?: EspComposeElement | EspComposeElement[];
+    /** Padding around the page content. Token name or pixel value. */
+    padding?: SpacingToken | number;
+    /** Skip this page in the page list. */
+    skip?: boolean;
+    /** Background color override (hex). If omitted, uses theme background. */
+    bgColor?: string;
+    /** Border width in pixels. Default: 0. */
+    borderWidth?: number;
+    /** Border color (hex). */
+    borderColor?: string;
+}
+/**
+ * Screen — a top-level LVGL page container.
+ *
+ * Applies the active theme's background color by default.
+ *
+ * @example
+ * <Screen padding="lg">
+ *   <VStack gap="md">
+ *     <Text variant="title">Home</Text>
+ *     <Button text="Toggle" />
+ *   </VStack>
+ * </Screen>
+ */
+declare const Screen: _esphome_compose.IntentComponent<ScreenProps, readonly ["lvgl:widget"], readonly ["lvgl:widget"], undefined, undefined>;
+
+type FlexAlign$1 = 'START' | 'CENTER' | 'END' | 'SPACE_BETWEEN' | 'SPACE_AROUND' | 'SPACE_EVENLY';
+type CrossAlign$1 = 'START' | 'CENTER' | 'END' | 'STRETCH';
+interface SpaceProps {
+    children?: EspComposeElement | EspComposeElement[];
+    /** Layout direction. Default: 'vertical'. */
+    direction?: 'horizontal' | 'vertical';
+    /** Gap between children. Token name or pixel value. */
+    gap?: SpacingToken | number;
+    /** Padding around the container. Token name or pixel value. */
+    padding?: SpacingToken | number;
+    /** Main axis alignment. */
+    align?: FlexAlign$1;
+    /** Cross axis alignment. */
+    crossAlign?: CrossAlign$1;
+    /** Enable wrapping (ROW_WRAP / COLUMN_WRAP). Default: false. */
+    wrap?: boolean;
+    /** Width. Numeric pixels, percentage string, or 'SIZE_CONTENT'. */
+    width?: number | string;
+    /** Height. Numeric pixels, percentage string, or 'SIZE_CONTENT'. */
+    height?: number | string;
+    /** Background color (hex). */
+    bgColor?: string;
+    /** Background opacity. */
+    bgOpa?: 'TRANSP' | 'COVER';
+    /** Border radius. */
+    radius?: number;
+    /** Border width in pixels. Default: 0. */
+    borderWidth?: number;
+    /** Border color (hex). */
+    borderColor?: string;
+}
+/**
+ * Flexible space layout — arranges children along a direction.
+ *
+ * Similar to AntD's `<Space>`. Defaults to vertical (column) layout.
+ * Supports wrapping via the `wrap` prop.
+ *
+ * @example
+ * <Space direction="horizontal" gap="md" align="SPACE_BETWEEN">
+ *   <Text>Left</Text>
+ *   <Text>Right</Text>
+ * </Space>
+ *
+ * <Space gap="lg" wrap>
+ *   <Button text="A" />
+ *   <Button text="B" />
+ *   <Button text="C" />
+ * </Space>
+ */
+declare const Space: _esphome_compose.IntentComponent<SpaceProps, readonly ["lvgl:widget"], readonly ["lvgl:widget"], undefined, true>;
+/**
+ * Vertical stack layout — shorthand for `<Space direction="vertical">`.
+ *
+ * @example
+ * <VStack gap="md" padding="lg">
+ *   <Text variant="title">Hello</Text>
+ *   <Button text="Click me" />
+ * </VStack>
+ */
+declare const VStack: _esphome_compose.IntentComponent<Omit<SpaceProps, "direction">, readonly ["lvgl:widget"], readonly ["lvgl:widget"], undefined, true>;
+/**
+ * Horizontal stack layout — shorthand for `<Space direction="horizontal">`.
+ *
+ * @example
+ * <HStack gap="sm" align="SPACE_BETWEEN">
+ *   <Text>Left</Text>
+ *   <Text>Right</Text>
+ * </HStack>
+ */
+declare const HStack: _esphome_compose.IntentComponent<Omit<SpaceProps, "direction">, readonly ["lvgl:widget"], readonly ["lvgl:widget"], undefined, true>;
+
+type FlexAlign = 'START' | 'CENTER' | 'END' | 'SPACE_BETWEEN' | 'SPACE_AROUND' | 'SPACE_EVENLY';
+type CrossAlign = 'START' | 'CENTER' | 'END' | 'STRETCH';
+interface RowProps {
+    children?: EspComposeElement | EspComposeElement[];
+    /** Horizontal gutter (space between columns). Token or pixel value. */
+    gutter?: SpacingToken | number | [SpacingToken | number, SpacingToken | number];
+    /** Main-axis justify. Default: 'START'. */
+    justify?: FlexAlign;
+    /** Cross-axis alignment. Default: 'START'. */
+    align?: CrossAlign;
+    /** Whether row wraps. Default: true. */
+    wrap?: boolean;
+    /** Width. Default: '100%'. */
+    width?: number | string;
+    /** Height. */
+    height?: number | string;
+    /** Border width in pixels. Default: 0. */
+    borderWidth?: number;
+    /** Border color (hex). */
+    borderColor?: string;
+}
+/**
+ * Row — a horizontal flex container that wraps children.
+ *
+ * @example
+ * <Row gutter="md" justify="SPACE_BETWEEN">
+ *   <Col span={12}><Text text="Left" /></Col>
+ *   <Col span={12}><Text text="Right" /></Col>
+ * </Row>
+ */
+declare const Row: _esphome_compose.IntentComponent<RowProps, readonly ["lvgl:widget"], readonly ["compose-ui:col"], undefined, true>;
+interface ColProps {
+    children?: EspComposeElement | EspComposeElement[];
+    /**
+     * Proportional width (flex_grow value).
+     * Like AntD's `span` but using flex_grow instead of a 24-column grid.
+     * A Col with span={2} takes twice the space of span={1}.
+     * Default: 1.
+     */
+    span?: number;
+    /** Width override (disables flex_grow). */
+    width?: number | string;
+    /** Height. */
+    height?: number | string;
+    /** Border width in pixels. Default: 0. */
+    borderWidth?: number;
+    /** Border color (hex). */
+    borderColor?: string;
+}
+/**
+ * Col — a column within a Row that uses `flex_grow` for proportional sizing.
+ *
+ * @example
+ * <Row gutter="sm">
+ *   <Col span={1}><Text text="1/3" /></Col>
+ *   <Col span={2}><Text text="2/3" /></Col>
+ * </Row>
+ */
+declare const Col: _esphome_compose.IntentComponent<ColProps, readonly ["compose-ui:col", "lvgl:widget"], readonly ["lvgl:widget"], undefined, true>;
+
+/**
+ * Column/row track definition.
+ * - `FR(n)` — fractional unit (string, passed through to ESPHome)
+ * - number  — fixed pixel size
+ * - 'SIZE_CONTENT' — auto-size to content
+ */
+type TrackSize = string | number;
+type GridAlign = 'START' | 'CENTER' | 'END' | 'STRETCH';
+interface GridProps {
+    children?: EspComposeElement | EspComposeElement[];
+    /** Column track definitions. E.g. ['FR(1)', 'FR(2)', 200] */
+    columns: TrackSize[];
+    /** Row track definitions. E.g. ['FR(1)', 100] */
+    rows: TrackSize[];
+    /** Column gap. Token or pixels. */
+    columnGap?: SpacingToken | number;
+    /** Row gap. Token or pixels. */
+    rowGap?: SpacingToken | number;
+    /** Shorthand for equal column and row gap. */
+    gap?: SpacingToken | number;
+    /** Default column alignment for children. */
+    alignColumns?: GridAlign;
+    /** Default row alignment for children. */
+    alignRows?: GridAlign;
+    /** Width. */
+    width?: number | string;
+    /** Height. */
+    height?: number | string;
+    /** Background color. */
+    bgColor?: string;
+    /** Background opacity. */
+    bgOpa?: 'TRANSP' | 'COVER';
+    /** Border width in pixels. Default: 0. */
+    borderWidth?: number;
+    /** Border color (hex). */
+    borderColor?: string;
+}
+/**
+ * Grid — a native CSS Grid container for LVGL.
+ *
+ * @example
+ * <Grid columns={['FR(1)', 'FR(1)']} rows={['FR(1)', 'FR(1)']}>
+ *   <GridItem col={0} row={0}><Text text="Top-left" /></GridItem>
+ *   <GridItem col={1} row={0}><Text text="Top-right" /></GridItem>
+ *   <GridItem col={0} row={1} colSpan={2}><Text text="Full bottom" /></GridItem>
+ * </Grid>
+ */
+declare const Grid: _esphome_compose.IntentComponent<GridProps, readonly ["lvgl:widget"], readonly ["compose-ui:grid-item"], undefined, true>;
+interface GridItemProps {
+    children?: EspComposeElement | EspComposeElement[];
+    /** Column position (0-based). */
+    col: number;
+    /** Row position (0-based). */
+    row: number;
+    /** Number of columns to span. Default: 1. */
+    colSpan?: number;
+    /** Number of rows to span. Default: 1. */
+    rowSpan?: number;
+    /** Column alignment override. */
+    colAlign?: GridAlign;
+    /** Row alignment override. */
+    rowAlign?: GridAlign;
+    /** Border width in pixels. Default: 0. */
+    borderWidth?: number;
+    /** Border color (hex). */
+    borderColor?: string;
+}
+/**
+ * GridItem — positions a child within a Grid.
+ *
+ * @example
+ * <GridItem col={0} row={0} colSpan={2}>
+ *   <Text text="Spans two columns" />
+ * </GridItem>
+ */
+declare const GridItem: _esphome_compose.IntentComponent<GridItemProps, readonly ["compose-ui:grid-item", "lvgl:widget"], readonly ["lvgl:widget"], undefined, true>;
+
+interface TextProps {
+    children?: EspComposeElement | EspComposeElement[];
+    /** Typography variant. Determines font size. Default: 'body'. */
+    variant?: TextVariant;
+    /** Static text content. Use this or children. */
+    text?: string;
+    /** Text alignment within the label. */
+    align?: 'LEFT' | 'CENTER' | 'RIGHT' | 'AUTO';
+    /** Text color (hex). If omitted, uses theme textPrimary. */
+    color?: string;
+    /** Long text mode. */
+    longMode?: 'WRAP' | 'DOT' | 'SCROLL' | 'SCROLL_CIRCULAR' | 'CLIP';
+    /** X position (pixels). */
+    x?: number;
+    /** Y position (pixels). */
+    y?: number;
+    /** Width. */
+    width?: number | string;
+}
+/**
+ * Text — a styled label component.
+ *
+ * @example
+ * <Text variant="title">Living Room</Text>
+ * <Text variant="caption" color="#888888">Last updated: 5m ago</Text>
+ */
+declare const Text: _esphome_compose.IntentComponent<TextProps, readonly ["lvgl:widget"], readonly [], undefined, undefined>;
+
+type ButtonVariant = 'solid' | 'outline';
+interface ButtonProps {
+    /** Button label text. */
+    text?: string;
+    /** Color scheme. Default: 'primary'. */
+    status?: StatusToken;
+    /** Size. Default: 'md'. */
+    size?: SizeToken;
+    /** Visual variant. Default: 'solid'. */
+    variant?: ButtonVariant;
+    /** X position (pixels). */
+    x?: number;
+    /** Y position (pixels). */
+    y?: number;
+    /** Width override. */
+    width?: number | string;
+    /** Height override. */
+    height?: number | string;
+    /** Press handler (ESPHome action). */
+    onPress?: unknown;
+}
+/**
+ * Button — a styled, clickable button with a label.
+ *
+ * @example
+ * <Button text="Toggle Light" status="primary" size="lg" />
+ * <Button text="Delete" status="danger" variant="outline" />
+ */
+declare const Button: _esphome_compose.IntentComponent<ButtonProps, readonly ["lvgl:widget"], readonly [], undefined, undefined>;
+
+interface CardProps {
+    children?: EspComposeElement | EspComposeElement[];
+    /** Padding inside the card. Default: 'md'. */
+    padding?: SpacingToken | number;
+    /** Corner radius. Default: 'md'. */
+    radius?: RadiusToken | number;
+    /** Background color (hex). Default: theme surfaceAlt. */
+    bgColor?: string;
+    /** Border color (hex). */
+    borderColor?: string;
+    /** Border width. Default: 0. */
+    borderWidth?: number;
+    /** Width. */
+    width?: number | string;
+    /** Height. */
+    height?: number | string;
+    /** Gap between children. Token name or pixel value. */
+    gap?: SpacingToken | number;
+}
+/**
+ * Card — a styled container with background and rounded corners.
+ *
+ * @example
+ * <Card>
+ *   <Text variant="title">Living Room</Text>
+ *   <SliderField label="Brightness" />
+ * </Card>
+ */
+declare const Card: _esphome_compose.IntentComponent<CardProps, readonly ["lvgl:widget"], readonly ["lvgl:widget"], undefined, true>;
+
+interface SliderFieldProps {
+    /** Label text displayed above the slider. */
+    label: string;
+    /** Bound value (sensor or entity reference). */
+    value?: unknown;
+    /** Change handler (ESPHome action). */
+    onChange?: unknown;
+    /** Minimum value. Default: 0. */
+    min?: number;
+    /** Maximum value. Default: 100. */
+    max?: number;
+    /** Gap between label and slider. Default: 'xs'. */
+    gap?: SpacingToken | number;
+    /** Width of the field container. */
+    width?: number | string;
+}
+/**
+ * SliderField — a label + slider composite.
+ *
+ * @example
+ * <SliderField label="Brightness" min={0} max={255} />
+ */
+declare const SliderField: _esphome_compose.IntentComponent<SliderFieldProps, readonly ["lvgl:widget"], readonly [], undefined, undefined>;
+
+/**
+ * SwitchField — a label + switch in a row layout.
+ *
+ * Compiles to a container with a label and a switch widget.
+ */
+interface SwitchFieldProps {
+    /** Label text displayed next to the switch. */
+    label: string;
+    /** Bound value (sensor or entity reference). */
+    value?: unknown;
+    /** Change handler (ESPHome action). */
+    onChange?: unknown;
+    /** Width of the field container. */
+    width?: number | string;
+}
+/**
+ * SwitchField — a label + switch in a row layout.
+ *
+ * @example
+ * <SwitchField label="Lamp" />
+ */
+declare const SwitchField: _esphome_compose.IntentComponent<SwitchFieldProps, readonly ["lvgl:widget"], readonly [], undefined, undefined>;
+
+interface DropdownFieldProps {
+    /** Label text displayed above the dropdown. */
+    label: string;
+    /** Newline-separated option values (ESPHome LVGL format). */
+    options: string;
+    /** Bound selection index. */
+    value?: unknown;
+    /** Change handler (ESPHome action). */
+    onChange?: unknown;
+    /** Gap between label and dropdown. Default: 'xs'. */
+    gap?: SpacingToken | number;
+    /** Width of the field container. */
+    width?: number | string;
+}
+/**
+ * DropdownField — a label + dropdown composite.
+ *
+ * @example
+ * <DropdownField label="Mode" options={"Auto\nCool\nHeat"} />
+ */
+declare const DropdownField: _esphome_compose.IntentComponent<DropdownFieldProps, readonly ["lvgl:widget"], readonly [], undefined, undefined>;
+
+export { Button, COMPOSE_UI_INTENTS, Card, Col, DropdownField, type FontDef, Grid, GridItem, HStack, type RadiusToken, Row, Screen, type SizeDimensions, type SizeToken, SliderField, Space, type SpacingToken, type StatusColors, type StatusToken, SwitchField, Text, type TextVariant, type Theme, type ThemeColors, ThemeContext, ThemeProvider, type ThemeTypography, type TrackSize, VStack, darkTheme, fontDefToLvgl, lightTheme, resolveRadius, resolveSize, resolveSpacing, resolveStatus, resolveTypography, themeFromJSON, themeToJSON, useTheme };