@luzmo/lucero 1.0.3-alpha.9 → 2.0.1

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;