@luzmo/lucero 1.0.3-alpha.9 → 2.0.0

package/components/question-box/index.js

@@ -0,0 +1,25 @@
+/*! * Lucero - The design system for Luzmo.
+ * 
+ * Copyright © 2025 Luzmo
+ * All rights reserved.
+ * Lucero (“Luzmo Design System”) must be used according to the Luzmo Terms of Service.
+ * This license allows users with a current active Luzmo account to use Lucero.
+ * This license terminates automatically if a user no longer has an active Luzmo account.
+ * Please view the Luzmo Terms of Service at: https://www.luzmo.com/information-pages/terms-of-use.
+ * 
+ * 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.
+ * */
+(() => {
+	if (typeof document < "u" && !document.querySelector("style[data-luzmo-vars]")) {
+		let e = document.createElement("style");
+		e.setAttribute("data-luzmo-vars", ""), e.textContent = "html{--luzmo-animation-duration: 0.15s;--luzmo-border-color: rgba(var(--luzmo-border-color-rgb), 0.1);--luzmo-border-color-hover: rgba(var(--luzmo-border-color-rgb), 0.15);--luzmo-border-color-down: rgba(var(--luzmo-border-color-rgb), 0.3);--luzmo-border-color-focus: rgba(var(--luzmo-border-color-rgb), 0.15);--luzmo-border-color-rgb: 0, 0, 0;--luzmo-border-color-full: rgb(180, 180, 180);--luzmo-border-color-full-hover: color-mix(in oklch, var(--luzmo-border-color-full), black 25%);--luzmo-border-color-full-down: color-mix(in oklch, var(--luzmo-border-color-full), black 45%);--luzmo-border-color-full-focus: color-mix(in oklch, var(--luzmo-border-color-full), black 25%);--luzmo-border-color-disabled: #dddddd;--luzmo-border-radius: 6px;--luzmo-border-radius-s: 4px;--luzmo-border-radius-l: 8px;--luzmo-border-radius-xl: 12px;--luzmo-border-radius-full: 999rem;--luzmo-border-width: 1px;--luzmo-shadow-color-rgb: 0, 0, 0;--luzmo-shadow-opacity: 0.1;--luzmo-shadow-color: rgba( var(--luzmo-shadow-color-rgb), var(--luzmo-shadow-opacity) );--luzmo-font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Oxygen-Sans, Ubuntu, Cantarell, \"Helvetica Neue\", Helvetica, Arial, sans-serif;--luzmo-font-size-xs: 10px;--luzmo-font-size-s: 12px;--luzmo-font-size-m: 14px;--luzmo-font-size: 14px;--luzmo-font-size-l: 16px;--luzmo-font-size-xl: 18px;--luzmo-font-size-xxl: 20px;--luzmo-font-style: normal;--luzmo-line-height: normal;--luzmo-font-weight: 400;--luzmo-font-weight-semibold: 500;--luzmo-font-weight-bold: 600;--luzmo-font-color: #333;--luzmo-font-color-disabled: var(--luzmo-disabled-color);--luzmo-font-color-extra-dimmed: #888;--luzmo-font-color-hover: color-mix(in oklch, var(--luzmo-font-color), black 8%);--luzmo-font-color-down: color-mix(in oklch, var(--luzmo-font-color), black 20%);--luzmo-font-color-focus: color-mix(in oklch, var(--luzmo-font-color), black 8%);--luzmo-primary: #4434ff;--luzmo-primary-hover: color-mix(in oklch, var(--luzmo-primary), black 8%);--luzmo-primary-down: color-mix(in oklch, var(--luzmo-primary), black 20%);--luzmo-primary-focus: color-mix(in oklch, var(--luzmo-primary), black 8%);--luzmo-primary-inverse-color: #ffffff;--luzmo-accent-on-subtle-color: var(--luzmo-primary);--luzmo-primary-rgb: 68, 52, 255;--luzmo-background-color: #ffffff;--luzmo-background-color-rgb: 255, 255, 255;--luzmo-background-color-disabled: #eeeeee;--luzmo-background-color-hover: color-mix(in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 5%), black 1.5%);--luzmo-background-color-down: color-mix(in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 7%), black 1%);--luzmo-background-color-focus: color-mix(in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 5%), black 1.5%);--luzmo-background-color-highlight: rgb(240, 240, 240);--luzmo-background-color-highlight-disabled: rgb(245, 245, 245);--luzmo-background-color-highlight-hover: color-mix(in oklch, var(--luzmo-background-color-highlight), black 10%);--luzmo-background-color-highlight-down: color-mix(in oklch, var(--luzmo-background-color-highlight), black 20%);--luzmo-background-color-highlight-focus: color-mix(in oklch, var(--luzmo-background-color-highlight), black 10%);--luzmo-secondary: #d000d0;--luzmo-secondary-hover: color-mix(in oklch, var(--luzmo-secondary), black 8%);--luzmo-secondary-down: color-mix(in oklch, var(--luzmo-secondary), black 20%);--luzmo-secondary-focus: color-mix(in oklch, var(--luzmo-secondary), black 8%);--luzmo-secondary-inverse-color: #ffffff;--luzmo-secondary-rgb: 208, 0, 208;--luzmo-scrollbar-size: 6px;--luzmo-scrollbar-thumb-background: rgba(var(--luzmo-border-color-rgb), 0.3);--luzmo-scrollbar-thumb-border-radius: var(--luzmo-border-radius-s);--luzmo-scrollbar-thumb-hover-background: rgba( var(--luzmo-border-color-rgb), 0.4 );--luzmo-scrollbar-track-background: transparent;--luzmo-scrollbar-track-border-radius: var(--luzmo-border-radius-s);--luzmo-scrollbar-width: thin;--luzmo-negative-color: #ca221c;--luzmo-negative-color-hover: color-mix(in oklch, var(--luzmo-negative-color), black 8%);--luzmo-negative-color-down: color-mix(in oklch, var(--luzmo-negative-color), black 20%);--luzmo-negative-color-focus: color-mix(in oklch, var(--luzmo-negative-color), black 8%);--luzmo-negative-on-subtle-color: var(--luzmo-negative-color);--luzmo-negative-color-rgb: 202, 34, 28;--luzmo-negative-inverse-color: #ffffff;--luzmo-positive-color: rgb(18, 133, 90);--luzmo-positive-color-hover: color-mix(in oklch, var(--luzmo-positive-color), black 8%);--luzmo-positive-color-down: color-mix(in oklch, var(--luzmo-positive-color), black 20%);--luzmo-positive-color-focus: color-mix(in oklch, var(--luzmo-positive-color), black 8%);--luzmo-positive-on-subtle-color: color-mix( in oklch, var(--luzmo-positive-color), var(--luzmo-font-color) 11% );--luzmo-positive-color-rgb: 18, 133, 90;--luzmo-positive-inverse-color: #ffffff;--luzmo-selected-color: rgb(110, 110, 110);--luzmo-selected-color-hover: color-mix(in oklch, var(--luzmo-selected-color), black 25%);--luzmo-selected-color-down: color-mix(in oklch, var(--luzmo-selected-color), black 45%);--luzmo-selected-color-focus: color-mix(in oklch, var(--luzmo-selected-color), black 25%);--luzmo-selected-color-hard: #1e1e1e;--luzmo-selected-color-hard-hover: color-mix(in oklch, var(--luzmo-selected-color-hard), black 25%);--luzmo-selected-color-hard-down: color-mix(in oklch, var(--luzmo-selected-color-hard), black 45%);--luzmo-selected-color-hard-focus: color-mix(in oklch, var(--luzmo-selected-color-hard), black 25%);--luzmo-neutral-on-subtle-color: var(--luzmo-selected-color-hard);--luzmo-informative-color: #1670dd;--luzmo-informative-color-hover: color-mix(in oklch, var(--luzmo-informative-color), black 8%);--luzmo-informative-color-down: color-mix(in oklch, var(--luzmo-informative-color), black 20%);--luzmo-informative-color-focus: var(--luzmo-informative-color-hover);--luzmo-informative-on-subtle-color: color-mix( in oklch, var(--luzmo-informative-color), var(--luzmo-font-color) 9% );--luzmo-informative-color-rgb: 22, 112, 221;--luzmo-informative-inverse-color: #ffffff;--luzmo-notice-color: rgb(229, 127, 0);--luzmo-notice-color-hover: color-mix(in oklch, var(--luzmo-notice-color), black 8%);--luzmo-notice-color-down: color-mix(in oklch, var(--luzmo-notice-color), black 20%);--luzmo-notice-color-focus: var(--luzmo-notice-color-hover);--luzmo-notice-on-subtle-color: color-mix( in oklch, var(--luzmo-notice-color), var(--luzmo-font-color) 40% );--luzmo-notice-inverse-color: var(--luzmo-selected-color-hard);--luzmo-seafoam-color: rgb(0, 140, 140);--luzmo-indigo-color: rgb(68, 52, 255);--luzmo-purple-color: rgb(112, 48, 210);--luzmo-fuchsia-color: rgb(205, 30, 170);--luzmo-magenta-color: rgb(203, 36, 98);--luzmo-yellow-color: rgb(228, 208, 0);--luzmo-gray-color: rgb(110, 110, 110);--luzmo-red-color: rgb(202, 34, 28);--luzmo-orange-color: rgb(218, 123, 17);--luzmo-chartreuse-color: rgb(85, 135, 0);--luzmo-celery-color: rgb(48, 134, 22);--luzmo-green-color: rgb(18, 133, 90);--luzmo-cyan-color: rgb(0, 134, 180);--luzmo-blue-color: rgb(22, 112, 221);--luzmo-disabled-color: #aaaaaa;--luzmo-spacing-1: 2px;--luzmo-spacing-2: 4px;--luzmo-spacing-3: 8px;--luzmo-spacing-4: 12px;--luzmo-spacing-5: 16px;--luzmo-indicator-gap: 2px;--luzmo-indicator-width: 1px;--luzmo-indicator-color: var(--luzmo-primary);--luzmo-component-height-xxs: 20px;--luzmo-component-height-xs: 24px;--luzmo-component-height-s: 28px;--luzmo-component-height: 32px;--luzmo-component-height-l: 40px;--luzmo-component-height-xl: 48px;--luzmo-component-height-xxl: 64px;--luzmo-icon-size-xxs: 10px;--luzmo-icon-size-xs: 12px;--luzmo-icon-size-s: 14px;--luzmo-icon-size-m: 16px;--luzmo-icon-size-l: 18px;--luzmo-icon-size-xl: 20px;--luzmo-icon-size-xxl: 32px}html.dark,html.dark-theme,:where(.dark-theme){--luzmo-border-color: rgba(var(--luzmo-border-color-rgb), 0.2);--luzmo-border-color-hover: rgba(var(--luzmo-border-color-rgb), 0.3);--luzmo-border-color-down: rgba(var(--luzmo-border-color-rgb), 0.35);--luzmo-border-color-focus: rgba(var(--luzmo-border-color-rgb), 0.3);--luzmo-border-color-rgb: 255, 255, 255;--luzmo-border-color-full: #4c4c57;--luzmo-border-color-full-hover: color-mix(in oklch, var(--luzmo-border-color-full), white 20%);--luzmo-border-color-full-down: color-mix(in oklch, var(--luzmo-border-color-full), white 35%);--luzmo-border-color-full-focus: color-mix(in oklch, var(--luzmo-border-color-full), white 20%);--luzmo-border-color-disabled: #333;--luzmo-shadow-opacity: 0.35;--luzmo-shadow-color: rgba( var(--luzmo-shadow-color-rgb), var(--luzmo-shadow-opacity) );--luzmo-font-color: #ced4da;--luzmo-font-color-extra-dimmed: #72787f;--luzmo-font-color-hover: color-mix(in oklch, var(--luzmo-font-color), white 8%);--luzmo-font-color-down: color-mix(in oklch, var(--luzmo-font-color), white 20%);--luzmo-font-color-focus: color-mix(in oklch, var(--luzmo-font-color), white 8%);--luzmo-primary: #7b90ff;--luzmo-primary-hover: color-mix(in oklch, var(--luzmo-primary), white 12%);--luzmo-primary-down: color-mix(in oklch, var(--luzmo-primary), white 24%);--luzmo-primary-focus: color-mix(in oklch, var(--luzmo-primary), white 12%);--luzmo-accent-on-subtle-color: color-mix( in oklch, var(--luzmo-primary), var(--luzmo-font-color) 1% );--luzmo-background-color: #262626;--luzmo-background-color-rgb: 0, 0, 0;--luzmo-background-color-disabled: #939ea8;--luzmo-background-color-hover: color-mix(in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 3%), white 14%);--luzmo-background-color-down: color-mix(in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 3%), white 25%);--luzmo-background-color-focus: color-mix(in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 3%), white 14%);--luzmo-background-color-highlight: rgb(72, 72, 72);--luzmo-background-color-highlight-disabled: #313131;--luzmo-background-color-highlight-hover: color-mix(in oklch, var(--luzmo-background-color-highlight), white 20%);--luzmo-background-color-highlight-down: color-mix(in oklch, var(--luzmo-background-color-highlight), white 35%);--luzmo-background-color-highlight-focus: color-mix(in oklch, var(--luzmo-background-color-highlight), white 20%);--luzmo-primary-inverse-color: var(--luzmo-background-color);--luzmo-indicator-color: var(--luzmo-primary);--luzmo-primary-rgb: 94, 113, 208;--luzmo-secondary: #ebff00;--luzmo-secondary-inverse-color: #333;--luzmo-secondary-rgb: 200, 219, 0;--luzmo-negative-color: #f76d74;--luzmo-negative-color-hover: color-mix(in oklch, var(--luzmo-negative-color), white 12%);--luzmo-negative-color-down: color-mix(in oklch, var(--luzmo-negative-color), white 24%);--luzmo-negative-color-focus: color-mix(in oklch, var(--luzmo-negative-color), white 12%);--luzmo-negative-on-subtle-color: color-mix( in oklch, var(--luzmo-negative-color), var(--luzmo-font-color) 40% );--luzmo-negative-color-rgb: 247, 109, 116;--luzmo-negative-inverse-color: var(--luzmo-background-color);--luzmo-positive-color: #39a875;--luzmo-positive-color-hover: color-mix(in oklch, var(--luzmo-positive-color), white 12%);--luzmo-positive-color-down: color-mix(in oklch, var(--luzmo-positive-color), white 24%);--luzmo-positive-color-focus: color-mix(in oklch, var(--luzmo-positive-color), white 12%);--luzmo-positive-on-subtle-color: color-mix( in oklch, var(--luzmo-positive-color), var(--luzmo-font-color) 35% );--luzmo-positive-color-rgb: 57, 168, 117;--luzmo-positive-inverse-color: var(--luzmo-background-color);--luzmo-selected-color: #afafaf;--luzmo-selected-color-hover: color-mix(in oklch, var(--luzmo-selected-color), white 20%);--luzmo-selected-color-down: color-mix(in oklch, var(--luzmo-selected-color), white 35%);--luzmo-selected-color-focus: color-mix(in oklch, var(--luzmo-selected-color), white 20%);--luzmo-selected-color-hard: #e9e9e9;--luzmo-selected-color-hard-hover: color-mix(in oklch, var(--luzmo-selected-color-hard), white 20%);--luzmo-selected-color-hard-down: color-mix(in oklch, var(--luzmo-selected-color-hard), white 35%);--luzmo-selected-color-hard-focus: color-mix(in oklch, var(--luzmo-selected-color-hard), white 20%);--luzmo-neutral-on-subtle-color: var(--luzmo-selected-color-hard);--luzmo-informative-color: #5c94ff;--luzmo-informative-color-hover: color-mix(in oklch, var(--luzmo-informative-color), white 12%);--luzmo-informative-color-down: color-mix(in oklch, var(--luzmo-informative-color), white 24%);--luzmo-informative-color-focus: var(--luzmo-informative-color-hover);--luzmo-informative-on-subtle-color: color-mix( in oklch, var(--luzmo-informative-color), var(--luzmo-font-color) 36% );--luzmo-informative-color-rgb: 92, 148, 255;--luzmo-informative-inverse-color: var(--luzmo-background-color);--luzmo-notice-color-hover: color-mix(in oklch, var(--luzmo-notice-color), white 12%);--luzmo-notice-color-down: color-mix(in oklch, var(--luzmo-notice-color), white 24%);--luzmo-notice-color-focus: var(--luzmo-notice-color-hover);--luzmo-notice-on-subtle-color: var(--luzmo-notice-color);--luzmo-notice-inverse-color: var(--luzmo-background-color);--luzmo-disabled-color: #75797b}", document.head.appendChild(e);
+	}
+})();
+import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "../question-box-9F6Ppakl.js";
+export { e as DEFAULT_QUESTION_BOX_LABELS, o as LuzmoQuestionBox, r as QUESTION_BOX_OTHER_VALUE, a as questionBoxOtherKey, n as questionsToRequestedSchema, i as requestedSchemaToQuestions, t as toElicitationContent };

package/components/question-box/question-box-elicitation.d.ts

@@ -0,0 +1,58 @@
+import { type QuestionBoxQuestion, type QuestionBoxValue } from './types';
+/** One enum choice in the MCP form-mode subset (`const` + optional `title`). */
+export type QuestionBoxElicitationChoice = {
+    const: string;
+    title?: string;
+};
+/**
+ * A single property in a form-mode elicitation schema. Only the string, enum,
+ * and enum-array shapes the question box can render are produced; hosts may
+ * pass a wider MCP schema into {@link requestedSchemaToQuestions}.
+ */
+export type QuestionBoxElicitationProperty = {
+    type?: string;
+    title?: string;
+    description?: string;
+    default?: string | string[];
+    oneOf?: QuestionBoxElicitationChoice[];
+    enum?: string[];
+    enumNames?: string[];
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    items?: {
+        type?: string;
+        enum?: string[];
+        enumNames?: string[];
+        anyOf?: QuestionBoxElicitationChoice[];
+    };
+};
+/** Flat MCP `requestedSchema` for form-mode elicitation. */
+export type QuestionBoxRequestedSchema = {
+    type: 'object';
+    properties: Record<string, QuestionBoxElicitationProperty>;
+    required?: string[];
+};
+/**
+ * Maps question-box descriptors to an MCP form-mode `requestedSchema`.
+ * Lucero-only option fields (`description`, `hint`, `recommended`, `disabled`,
+ * `disabledReason`) are dropped. Other remains the reserved enum const and
+ * stores its text in a sibling string. A question without options becomes a
+ * single string property.
+ */
+export declare const questionsToRequestedSchema: (questions: QuestionBoxQuestion[]) => QuestionBoxRequestedSchema;
+/**
+ * Returns the live value as MCP elicitation `content`: Other remains the
+ * reserved enum const and its text uses `{id}Other`. A question without
+ * options returns its free-form text directly on `id`.
+ */
+export declare const toElicitationContent: (questions: QuestionBoxQuestion[], value: QuestionBoxValue) => QuestionBoxValue;
+/**
+ * Rebuilds question descriptors from an MCP `requestedSchema`. Number,
+ * boolean, constrained strings, malformed enums, and other unsupported
+ * properties are skipped. Lucero-only option fields cannot be recovered.
+ */
+export declare const requestedSchemaToQuestions: (schema: QuestionBoxRequestedSchema) => QuestionBoxQuestion[];

package/components/question-box/question-box-model.d.ts

@@ -0,0 +1,25 @@
+import { type QuestionBoxLabels, type QuestionBoxOption, type QuestionBoxQuestion, type QuestionBoxValue } from './types';
+export declare const cloneValue: (value: QuestionBoxValue) => QuestionBoxValue;
+export declare const setOwnValue: (value: QuestionBoxValue, key: string, entry: string | string[]) => void;
+export declare const valuesEqual: (left: QuestionBoxValue, right: QuestionBoxValue) => boolean;
+export declare const uniqueInOrder: (values: string[]) => string[];
+export declare const allowedValues: (question: QuestionBoxQuestion) => Set<string>;
+export declare const selectedValues: (question: QuestionBoxQuestion, value: QuestionBoxValue) => string[];
+export declare const isOtherSelected: (question: QuestionBoxQuestion, value: QuestionBoxValue) => boolean;
+export declare const mergeLabels: (labels: QuestionBoxLabels) => Required<QuestionBoxLabels>;
+export declare const interpolate: (template: string, replacements: Record<string, string>) => string;
+export declare const assertValidQuestions: (questions: QuestionBoxQuestion[]) => void;
+export declare const normalizeValue: (questions: QuestionBoxQuestion[], source: QuestionBoxValue) => QuestionBoxValue;
+/** Smallest number of answers a question accepts. */
+export declare const minimumSelected: (question: QuestionBoxQuestion) => number;
+/** Persistent constraint text for a multiple-choice group. */
+export declare const selectionRequirement: (question: QuestionBoxQuestion, labels: Required<QuestionBoxLabels>) => string | undefined;
+/** What keeps a question from being submitted, if anything. */
+export type QuestionBoxViolation = 'missing' | 'minimum' | 'maximum' | 'otherText';
+export declare const questionViolation: (question: QuestionBoxQuestion, value: QuestionBoxValue) => QuestionBoxViolation | undefined;
+export declare const questionInvalid: (question: QuestionBoxQuestion, value: QuestionBoxValue) => boolean;
+export declare const questionError: (question: QuestionBoxQuestion, value: QuestionBoxValue, labels: Required<QuestionBoxLabels>) => string | undefined;
+export declare const optionDisabled: (question: QuestionBoxQuestion, option: QuestionBoxOption, checked: boolean, value: QuestionBoxValue, disabled: boolean) => boolean;
+export declare const formatSelectedCount: (count: number, labels: Required<QuestionBoxLabels>) => string;
+export declare const formatAnswerList: (labels: string[], language: string) => string;
+export declare const formatOptionLabel: (option: QuestionBoxOption, labels: Required<QuestionBoxLabels>) => string;

package/components/question-box/question-box-templates.d.ts

@@ -0,0 +1,65 @@
+import { nothing, TemplateResult } from 'lit';
+import type { ElementSize } from '../../utils/sized-mixin';
+import { type QuestionBoxLabels, type QuestionBoxOption, type QuestionBoxOptionIndicator, type QuestionBoxQuestion, type QuestionBoxValue } from './types';
+/**
+ * Listeners the templates bind. Every entry is a stable field on the host, so
+ * re-rendering never rebinds a listener.
+ *
+ * @internal Not part of the `luzmo-question-box` public API.
+ */
+export type QuestionBoxRenderHandlers = {
+    contentClick: (event: MouseEvent) => void;
+    back: (event: Event) => void;
+    primary: () => void;
+    skip: (event: Event) => void;
+    cancel: (event: Event) => void;
+    change: () => void;
+    radioChange: (event: Event) => void;
+    radioClick: (event: Event) => void;
+    checkboxChange: (event: Event) => void;
+    otherInput: (event: Event) => void;
+    otherChange: (event: Event) => void;
+    otherKeydown: (event: KeyboardEvent) => void;
+    focusIn: (event: FocusEvent) => void;
+    focusOut: () => void;
+};
+/**
+ * Narrow, read-only view of the host state the templates read. Built by
+ * `LuzmoQuestionBox` on every render.
+ *
+ * @internal Not part of the `luzmo-question-box` public API.
+ */
+export type QuestionBoxRenderContext = {
+    questions: QuestionBoxQuestion[];
+    value: QuestionBoxValue;
+    copy: Required<QuestionBoxLabels>;
+    /** Zero-based index of the question being answered. */
+    step: number;
+    resolved: boolean;
+    submitted: boolean;
+    showError: boolean;
+    disabled: boolean;
+    readonly: boolean;
+    hideClose: boolean;
+    hideSkip: boolean;
+    showChange: boolean;
+    optionIndicator: QuestionBoxOptionIndicator;
+    size: ElementSize;
+    dir: 'ltr' | 'rtl';
+    /** Resolved language used for locale-aware answer lists. */
+    language: string;
+    selectedValues: (question: QuestionBoxQuestion) => string[];
+    isOtherSelected: (question: QuestionBoxQuestion) => boolean;
+    questionError: (question: QuestionBoxQuestion) => string | undefined;
+    /** Whether the question blocks the flow, with or without a message. */
+    questionInvalid: (question: QuestionBoxQuestion) => boolean;
+    optionDisabled: (question: QuestionBoxQuestion, option: QuestionBoxOption, checked: boolean) => boolean;
+    handlers: QuestionBoxRenderHandlers;
+};
+/**
+ * Renders the resolved summary or the current question card. Without a question
+ * there is nothing to answer, so the card and its border are left out entirely.
+ *
+ * @internal Not part of the `luzmo-question-box` public API.
+ */
+export declare function renderQuestionBox(context: QuestionBoxRenderContext): TemplateResult | typeof nothing;

package/components/question-box/question-box.d.ts

@@ -0,0 +1,182 @@
+import { CSSResultArray, nothing, PropertyValues, TemplateResult } from 'lit';
+import { LuzmoElement } from '../../utils/base';
+import '../action-button';
+import '../badge';
+import '../button';
+import '../checkbox';
+import '../field-group';
+import '../icon';
+import '../radio';
+import '../text-field';
+import { type QuestionBoxLabels, type QuestionBoxOptionIndicator, type QuestionBoxQuestion, type QuestionBoxValue } from './types';
+export type { QuestionBoxAction, QuestionBoxLabels, QuestionBoxOption, QuestionBoxOptionIndicator, QuestionBoxOtherConfig, QuestionBoxQuestion, QuestionBoxResultDetail, QuestionBoxValue } from './types';
+export type { QuestionBoxElicitationChoice, QuestionBoxElicitationProperty, QuestionBoxRequestedSchema } from './question-box-elicitation';
+export { questionsToRequestedSchema, requestedSchemaToQuestions, toElicitationContent } from './question-box-elicitation';
+export { DEFAULT_QUESTION_BOX_LABELS, QUESTION_BOX_OTHER_VALUE, questionBoxOtherKey } from './types';
+declare const LuzmoQuestionBox_base: typeof LuzmoElement & {
+    new (...args: any[]): import("../..").SizedElementInterface;
+    prototype: import("../..").SizedElementInterface;
+};
+/**
+ * @element luzmo-question-box
+ *
+ * Presents one or more single- or multiple-choice questions and returns a
+ * flat, elicitation-compatible answer object.
+ *
+ * @fires {Event} input - The in-progress answer value changed.
+ * @fires {Event} change - An answer was committed by the user.
+ * @fires {CustomEvent<QuestionBoxResultDetail>} luzmo-submit - The user accepted. `detail.action` is `accept`.
+ * @fires {CustomEvent<QuestionBoxResultDetail>} luzmo-decline - The user explicitly skipped the request. `detail.action` is `decline`.
+ * @fires {CustomEvent<QuestionBoxResultDetail>} luzmo-cancel - The user dismissed the interaction (Close, Escape, or `cancel()`). `detail.action` is `cancel`.
+ *
+ * @attr dir - Writing direction (`ltr` or `rtl`) propagated to composed controls.
+ * @attr hide-close - Hides the close action.
+ * @attr hide-skip - Hides Skip actions.
+ * @attr show-change - Shows a Change action after submission.
+ * @attr option-indicator - Selects `numbers` or `letters` for option indicators.
+ *
+ * @cssprop --luzmo-question-box-max-inline-size - Maximum inline size of the question box (`40rem` by default).
+ * @cssprop --luzmo-question-box-body-max-block-size - Maximum block size of the scrollable question body (`24rem` by default).
+ * @cssprop --luzmo-question-box-divider-width - Option separator width (`0px` by default).
+ * @cssprop --luzmo-question-box-divider-color - Option separator color.
+ * @cssprop --luzmo-question-box-selected-count-font-size - Selected-count and status text size, scaled with the component size.
+ * @cssprop --luzmo-question-box-descriptive-option-padding-block - Block padding for options when any option has a description.
+ * @cssprop --luzmo-question-box-focus-ring-width - Indicator focus ring width.
+ * @cssprop --luzmo-question-box-focus-ring-gap - Indicator focus ring offset.
+ * @cssprop --luzmo-question-box-focus-ring-color - Indicator focus ring color.
+ * @cssprop --luzmo-question-box-scrollbar-width - Scrollbar width of the question body.
+ * @cssprop --luzmo-question-box-scrollbar-track-background - Scrollbar track background of the question body.
+ * @cssprop --luzmo-question-box-scrollbar-track-border-radius - Scrollbar track corner radius of the question body.
+ * @cssprop --luzmo-question-box-scrollbar-thumb-background - Scrollbar thumb background of the question body.
+ * @cssprop --luzmo-question-box-scrollbar-thumb-border-radius - Scrollbar thumb corner radius of the question body.
+ * @cssprop --luzmo-question-box-scrollbar-thumb-hover-background - Scrollbar thumb background while hovered.
+ */
+export declare class LuzmoQuestionBox extends LuzmoQuestionBox_base {
+    static get styles(): CSSResultArray;
+    /**
+     * Questions to present, one per step. IDs must be unique JSON Schema
+     * property names.
+     */
+    questions: QuestionBoxQuestion[];
+    /**
+     * Live answers keyed by question ID. Other selection and accepted content
+     * use the reserved `__other__` enum const; free text uses `{id}Other`.
+     */
+    value: QuestionBoxValue;
+    /**
+     * Localizable UI copy. Omitted labels use the English defaults.
+     */
+    labels: QuestionBoxLabels;
+    /** Writing direction propagated to composed child controls. */
+    dir: 'ltr' | 'rtl';
+    /** Prevents interaction and removes controls from keyboard navigation. */
+    disabled: boolean;
+    /** Displays values without allowing the answers to be changed. */
+    readonly: boolean;
+    /** Hides the close action that emits `luzmo-cancel`. */
+    hideClose: boolean;
+    /** Hides Skip actions that emit `luzmo-decline`. */
+    hideSkip: boolean;
+    /** Shows a Change action after a successful submission. */
+    showChange: boolean;
+    /** Selects numbered or lettered visual option indicators. */
+    get optionIndicator(): QuestionBoxOptionIndicator;
+    set optionIndicator(value: QuestionBoxOptionIndicator);
+    private _optionIndicator;
+    private _step;
+    private _resolved;
+    private _submitted;
+    private _showError;
+    /** @internal */
+    private languageResolver;
+    private _radioChangeAdvanced;
+    /** @internal */
+    private multipleChoiceRoving;
+    /** @internal */
+    private questionTitle?;
+    /** @internal */
+    private otherField?;
+    /** @internal */
+    private optionsGroup?;
+    /** @internal */
+    private resolvedTitle?;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    disconnectedCallback(): void;
+    /** Moves focus to the active choices or the resolved-state focus target. */
+    focus(): void;
+    /** Returns whether every question currently has a valid answer. */
+    checkValidity(): boolean;
+    /** Validates the complete flow and emits `luzmo-submit` when it is valid. */
+    submit(): void;
+    /** Restores the first step with an empty answer object. */
+    reset(): void;
+    /** Dismisses the interaction and emits `luzmo-cancel`. */
+    cancel(): void;
+    protected willUpdate(changes: PropertyValues<this>): void;
+    protected updated(changes: PropertyValues): void;
+    protected render(): TemplateResult | typeof nothing;
+    /** @internal Narrow view of host state handed to the template functions. */
+    private get renderContext();
+    /** @internal Stable listener references, so re-rendering never rebinds. */
+    private get renderHandlers();
+    /** @internal */
+    private get copy();
+    /** @internal */
+    private get currentQuestion();
+    private handleKeydown;
+    private handleKeyup;
+    private handleFocusIn;
+    private handleContentClick;
+    /** @internal */
+    private optionShowsKeyboardFocus;
+    private handleFocusOut;
+    /**
+     * Flags the option that should carry a focus ring. A checkbox delegates focus
+     * to its inner input, so the option itself never matches `:focus-visible`.
+     * Focus moves between options are retargeted away at the host, so the
+     * listeners driving this live on the option group instead.
+     *
+     * @internal
+     */
+    private markKeyboardFocus;
+    /** @internal */
+    private focusedOptionForEvent;
+    private handleCancelClick;
+    private handleSkip;
+    private handleBack;
+    /** @internal */
+    private moveFocus;
+    /** @internal */
+    private focusOptions;
+    private handlePrimary;
+    /** @internal */
+    private advanceAfterSingleSelection;
+    /** @internal */
+    private acceptFlow;
+    private handleChange;
+    private handleRadioChange;
+    private handleRadioClick;
+    private handleCheckboxChange;
+    private handleOtherInput;
+    private handleOtherChange;
+    private handleOtherKeydown;
+    /** @internal */
+    private commitAnswer;
+    /** @internal */
+    private commitOther;
+    /** @internal */
+    private assignValue;
+    /** @internal */
+    private emitResult;
+    /** @internal */
+    private selectedValues;
+    /** @internal */
+    private isOtherSelected;
+    /** @internal */
+    private questionError;
+    /** @internal */
+    private questionInvalid;
+    /** @internal */
+    private optionDisabled;
+}

package/components/question-box/types.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Stable enum value used when the free-form Other choice is selected.
+ * Live values and MCP elicitation content keep this const; free text lives on
+ * `{id}Other`.
+ */
+export declare const QUESTION_BOX_OTHER_VALUE = "__other__";
+/** A selectable answer descriptor for a question. */
+export type QuestionBoxOption = {
+    /**
+     * Value returned to the consumer and used as an elicitation enum const.
+     * Must be a string. Never shown when `label` is set.
+     */
+    value: string;
+    /** Visible option label (elicitation `title`). */
+    label: string;
+    /** Optional supporting text rendered below the option label. */
+    description?: string;
+    /** Shows the localized recommended label beside this option. */
+    recommended?: boolean;
+    /**
+     * Optional muted hint shown beside the label.
+     * Lucero-only: dropped when mapping to elicitation `requestedSchema`.
+     */
+    hint?: string;
+    /**
+     * Lucero-only: option cannot be chosen. Dropped in elicitation mapping.
+     */
+    disabled?: boolean;
+    /**
+     * Lucero-only: explanation for a disabled option.
+     */
+    disabledReason?: string;
+};
+/** Localized copy for a question's free-form Other choice. */
+export type QuestionBoxOtherConfig = {
+    label?: string;
+    placeholder?: string;
+};
+/** A single step in a question-box flow. */
+export type QuestionBoxQuestion = {
+    /**
+     * Question id. Must be a valid JSON Schema property name (elicitation key).
+     */
+    id: string;
+    type: 'single' | 'multiple';
+    title: string;
+    description?: string;
+    required?: boolean;
+    default?: string | string[];
+    /** Maps to elicitation `minItems` for multiple questions. */
+    minSelected?: number;
+    /** Maps to elicitation `maxItems` for multiple questions. */
+    maxSelected?: number;
+    options: QuestionBoxOption[];
+    /**
+     * When true or an object, appends an Other choice.
+     * Free text is stored on {@link questionBoxOtherKey}.
+     */
+    other?: boolean | QuestionBoxOtherConfig;
+};
+/**
+ * Flat elicitation-shaped answers: question id → `string` | `string[]`,
+ * plus optional `{id}Other` strings.
+ */
+export type QuestionBoxValue = Record<string, string | string[] | undefined>;
+/** Visual marker used for regular answer choices. */
+export type QuestionBoxOptionIndicator = 'numbers' | 'letters';
+/** Localizable question-box copy and validation messages. */
+export type QuestionBoxLabels = {
+    continue?: string;
+    back?: string;
+    submit?: string;
+    skip?: string;
+    change?: string;
+    close?: string;
+    other?: string;
+    otherPlaceholder?: string;
+    recommended?: string;
+    answerTitle?: string;
+    answersTitle?: string;
+    /** `{current}` and `{total}` are replaced. */
+    progress?: string;
+    /** `{count}` is replaced when the selection is not exactly one. */
+    selectedCount?: string;
+    /** `{count}` is replaced when exactly one option is selected. */
+    selectedCountOne?: string;
+    /** `{label}` and `{recommended}` are replaced. */
+    recommendedSuffix?: string;
+    /** `{answer}` is replaced with the resolved answer. */
+    answer?: string;
+    /** Persistent, visually hidden guidance for a required multiple choice. */
+    requiredSelectionDescription?: string;
+    /** `{min}` and `{max}` are replaced in persistent selection guidance. */
+    selectionRangeDescription?: string;
+    /** `{min}` is replaced. */
+    minSelectedError?: string;
+    /** `{max}` is replaced. */
+    maxSelectedError?: string;
+    otherRequiredError?: string;
+};
+/**
+ * Result of leaving the flow: accepted answers, explicit refusal, or dismissal.
+ */
+export type QuestionBoxAction = 'accept' | 'decline' | 'cancel';
+/** Detail emitted by the `luzmo-submit`, `luzmo-decline`, and `luzmo-cancel` events. */
+export type QuestionBoxResultDetail = {
+    /** `decline` means Skip; `cancel` means Close, Escape, or `cancel()`. */
+    action: QuestionBoxAction;
+    /** Complete elicitation answers; present only for an accepted submission. */
+    content?: QuestionBoxValue;
+};
+/** Default English copy used for omitted {@link QuestionBoxLabels}. */
+export declare const DEFAULT_QUESTION_BOX_LABELS: Required<QuestionBoxLabels>;
+/**
+ * Returns the sibling key used to store free-form Other text for a question.
+ */
+export declare const questionBoxOtherKey: (questionId: string) => string;
+/**
+ * Returns whether a question includes a free-form Other choice. A question
+ * without options can only be answered in free form, so it always offers one.
+ */
+export declare const isQuestionBoxOtherEnabled: (question: QuestionBoxQuestion) => boolean;
+/** Normalizes an enabled Other choice to its optional localized configuration. */
+export declare const questionBoxOtherConfig: (question: QuestionBoxQuestion) => QuestionBoxOtherConfig;