uni-answer-sheet 1.0.6 → 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,534 @@
+/** JSON content shared across package boundaries; extensible node attributes. */
+interface JSONContent {
+    type?: string;
+    attrs?: Record<string, any>;
+    content?: JSONContent[];
+    marks?: {
+        type: string;
+        attrs?: Record<string, any>;
+    }[];
+    text?: string;
+}
+type ImageUploadHandler = (file: File) => Promise<string>;
+interface RichTextDocument {
+    version: 1;
+    content: JSONContent;
+}
+interface RichTextMetrics {
+    width: number;
+    height: number;
+    overflowing: boolean;
+}
+interface FlowSlice {
+    from: number;
+    to: number;
+    x: number;
+    y: number;
+}
+interface FlowUnit {
+    top: number;
+    bottom: number;
+}
+interface RichTextPagination {
+    slices: FlowSlice[];
+    /** Largest indivisible object that fits a full continuation column. */
+    maxUnitHeight?: number;
+    onMeasure: (units: FlowUnit[]) => void;
+    onActiveSliceChange?: (index: number) => void;
+}
+interface AnswerRegion {
+    id: string | null;
+    pos: number;
+    type: 'answerLine' | 'choiceMarker' | 'choiceOption' | 'answerCell';
+    attrs: Record<string, unknown>;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface RichTextEditorProps {
+    initialValue?: RichTextDocument;
+    readOnly?: boolean;
+    maxHeight?: number;
+    className?: string;
+    ariaLabel?: string;
+    choiceFillStyle?: 'bubble' | 'check' | 'box';
+    choiceFillPosition?: 'stem' | 'option';
+    choiceFillBindings?: ChoiceFillBinding[];
+    /** Highlight a host-selected question without changing the rich-text document. */
+    activeChoiceQuestionId?: string;
+    /** Optional host identities; ordinary editors remain independent of card data. */
+    contentTargets?: ContentTarget[];
+    allowContentAssignment?: boolean;
+    onContentSelect?: (id: string) => void;
+    pagination?: RichTextPagination;
+    /** Upload a selected file and return its image URL. Omit to embed a data URL. */
+    uploadImage?: ImageUploadHandler;
+    onChange?: (document: RichTextDocument) => void;
+    onLayout?: (metrics: RichTextMetrics) => void;
+}
+interface ContentTarget {
+    id: string;
+    label: string;
+    kind: 'question' | 'material';
+    parentId?: string;
+    choice?: boolean;
+    hideOptionsAtStem?: boolean;
+    inlineOptions?: boolean;
+    optionWidth?: number;
+}
+interface ChoiceFillBinding {
+    groupId: string;
+    questionId: string;
+    options: {
+        id: string;
+        label: string;
+        contentOptionId: string;
+    }[];
+}
+
+/** Versioned, structural protocol. No React, Tiptap or package dependency. */
+interface EditorStatus {
+    ready: boolean;
+    editable: boolean;
+    composing: boolean;
+    uploading: boolean;
+    layoutPending: boolean;
+    uploadError?: string;
+}
+interface EditorHandle {
+    getDocument(): RichTextDocument | null;
+    getAnswerRegions(): AnswerRegion[];
+    setDocument(value: RichTextDocument): void;
+    syncDocument(value: RichTextDocument): void;
+    focus(position?: 'start' | 'end'): void;
+    focusContent(id: string): boolean;
+    insertAnswerRegion(id: string, label: string, width?: number): void;
+    getStatus(): EditorStatus;
+}
+interface EditorInstance extends EditorHandle {
+    readonly ready: Promise<void>;
+    setOptions(options: Partial<RichTextEditorProps>): void;
+    destroy(): void;
+}
+interface QuestionHTMLCodec {
+    parse(html: string): RichTextDocument;
+    serialize(value: RichTextDocument): string;
+    unwrapParagraphs?(html: string, firstOnly?: boolean): string;
+}
+interface AnswerSheetEditorPlugin {
+    readonly kind: 'answer-sheet-editor';
+    readonly name: string;
+    readonly apiVersion: 1;
+    readonly documentVersion: 1;
+    /** The v1 surface exposes .rt-content and supports paginated flow slices. */
+    readonly capabilities: readonly string[];
+    /** Load the adapter before validating documents or using the HTML codec. */
+    prepare(): Promise<void>;
+    create(container: HTMLElement, options: RichTextEditorProps): EditorInstance;
+    readonly html: QuestionHTMLCodec;
+    /** Empty array means that the schema accepts the document. */
+    validateDocument(value: RichTextDocument): string[];
+}
+
+type ExerciseKind = 'judge' | 'fill' | 'answer' | 'calculation' | 'matching' | 'ordering' | 'correction' | 'drawing' | 'table' | 'writing' | 'english' | 'reading' | 'cloze' | 'completion' | 'chunk' | 'composite' | 'optional' | 'practice';
+type ItemKind = 'choice' | 'judge' | 'fill' | 'answer' | 'calculation' | 'correction' | 'drawing' | 'table' | 'writing' | 'english';
+type AreaStyle = 'blank' | 'lines' | 'grid' | 'characters' | 'four-lines' | 'coordinates';
+interface AnswerBlank {
+    id: string;
+    label: string;
+    width: number;
+    style: 'line' | 'brackets' | 'box' | 'characters';
+    characters: number;
+    score: number | null;
+    answers: string[];
+    prefix: string;
+    suffix: string;
+    breakAfter: boolean;
+}
+interface ScoringStep {
+    id: string;
+    label: string;
+    score: number | null;
+    prompt: string;
+    answer: string;
+}
+interface AnswerArea {
+    style: AreaStyle;
+    rows: number;
+    columns: number;
+    rowHeight: number;
+    wordMark: number;
+    title: boolean;
+    backgroundUrl: string;
+}
+interface ExerciseItem {
+    id: string;
+    label: string;
+    kind: ItemKind;
+    document: RichTextDocument;
+    score: number | null;
+    reference: RichTextDocument;
+    explanation: RichTextDocument;
+    choice: CardChoiceQuestion;
+    presentation: CardChoiceSettings['presentation'];
+    blanks: AnswerBlank[];
+    steps: ScoringStep[];
+    area: AnswerArea;
+    needsReason: boolean;
+    judgment: boolean | null;
+    targets: string[];
+}
+interface ExerciseOption {
+    id: string;
+    label: string;
+    text: string;
+    document?: RichTextDocument;
+}
+interface ExerciseSettings {
+    items: ExerciseItem[];
+    judgeLabels: 'symbols' | 'letters' | 'words';
+    fillNewLine: boolean;
+    pool: ExerciseOption[];
+    relation: 'one' | 'many';
+    reuseOptions: boolean;
+    matchingDisplay: 'letters' | 'lines';
+    ordering: 'sequence' | 'category';
+    sequence: string[];
+    categories: ExerciseOption[];
+    assignments: Record<string, string>;
+    chooseCount: number;
+    groupScore: number | null;
+    chunkText: string;
+    chunkPoints: {
+        id: string;
+        offset: number;
+        label: string;
+    }[];
+    chunkCorrect: string[];
+    chunkMax: number;
+    chunkScore: number | null;
+    attachmentUrl: string;
+}
+
+type ChoiceMarkerStyle = 'letter' | 'bubble' | 'check' | 'box';
+type ChoiceLayout = {
+    layout: 'fixed' | 'natural';
+    columns: number;
+    indent: boolean;
+    rowGap: number;
+    columnGap: number;
+    marker: ChoiceMarkerStyle;
+};
+
+interface ReferenceText {
+    content: RichTextDocument;
+    itemsContent: {
+        id: string;
+        key: string;
+        content: RichTextDocument;
+    }[];
+    groupId: string;
+    layout: ChoiceLayout;
+    numbered: boolean;
+}
+declare const questionTypes: {
+    readonly SCHOICE: "单选题";
+    readonly MCHOICE: "多选题";
+    readonly JUDGE: "判断题";
+    readonly FILLBLANK: "填空题";
+    readonly SHORTANSWER: "解答题";
+    readonly MIXED: "复合题";
+    readonly CLOZE: "完形填空";
+    readonly READTHENANSWER: "阅读理解";
+    readonly INFO_MATCHING: "信息匹配";
+    readonly TEXT_COMPLETION: "语法填空";
+    readonly ECOMPOSITION: "英语作文";
+    readonly CCOMPOSITION: "语文作文";
+    readonly CHUNK_CHOICE: "断句题";
+};
+type QuestionType = keyof typeof questionTypes;
+type AtomicType = Exclude<QuestionType, 'MIXED'>;
+interface ReferencePart {
+    referenceData?: Record<string, unknown>;
+    id: string;
+    label: string;
+    score: number | null;
+    width: number;
+    breakAfter: boolean;
+    height: number;
+    document: RichTextDocument;
+    choice: CardChoiceQuestion;
+    text?: ReferenceText;
+}
+interface ReferenceQuestion {
+    referenceData?: Record<string, unknown>;
+    id: string;
+    type: AtomicType;
+    label: string;
+    score: number | null;
+    choice: CardChoiceQuestion;
+    parts: ReferencePart[];
+    document: RichTextDocument;
+    height: number;
+    contentHeight: number;
+    characters: number;
+    lines: number;
+    halfPoint: boolean;
+    rightAnswers: number | null;
+    singleScore: number | null;
+    text?: ReferenceText;
+}
+interface ReferenceGroup {
+    sectionSeq?: string | number;
+    referenceData?: Record<string, unknown>;
+    textVersion?: 1;
+    material?: RichTextDocument;
+    type: QuestionType;
+    questions: ReferenceQuestion[];
+    layout: CardChoiceSettings;
+    fillNewLine: boolean;
+    optional: boolean;
+    choose: number;
+    optionalHeight: number;
+    scoreType?: 'LESS_SCORE' | 'ITEM_SCORE';
+}
+
+type CardPreset = 'a4' | 'a3-two' | 'a3-three';
+type BlockKind = 'choice' | ExerciseKind;
+type ChoiceScoreType = 'LESS_SCORE' | 'ITEM_SCORE';
+interface CardChoiceQuestion {
+    id: string;
+    label: string;
+    options: {
+        id: string;
+        label: string;
+    }[];
+    multiple: boolean;
+    indefinite?: boolean;
+    score?: number | null;
+    scoreType?: ChoiceScoreType;
+    lessScore?: number;
+    correctIds: string[];
+    breakBefore: boolean;
+    contentTarget?: {
+        groupId: string;
+        optionIds: string[];
+    } | null;
+}
+interface CardChoiceSettings {
+    source: 'manual' | 'content';
+    presentation: 'concentrated' | 'distributed' | 'stem' | 'option';
+    direction: 'row' | 'column';
+    rowsPerColumn: number;
+    marker: 'bubble' | 'check' | 'box';
+    rowGap: number;
+    columnGap: number;
+    questions: CardChoiceQuestion[];
+    questionState?: Record<string, Pick<CardChoiceQuestion, 'multiple' | 'correctIds' | 'breakBefore'>>;
+}
+interface CardBlock {
+    id: string;
+    title: string;
+    kind: BlockKind;
+    document: RichTextDocument;
+    answerHeight: number;
+    choices?: CardChoiceSettings;
+    exercise?: ExerciseSettings;
+    reference?: ReferenceGroup;
+}
+interface CardDocument {
+    version: 1;
+    questionCard?: boolean;
+    title: string;
+    preset: CardPreset;
+    margin: number;
+    gap: number;
+    creation?: CardCreation;
+    header?: CardHeaderSettings;
+    paperTitle?: CardPaperTitle;
+    blocks: CardBlock[];
+    scanMarking?: boolean;
+    halfPoint?: boolean;
+    choiceDirection?: 'row' | 'column';
+    mergeObjective?: boolean;
+}
+interface CardPaperTitle {
+    id: string;
+    document: RichTextDocument;
+    height: number;
+}
+interface CardCreation {
+    mode: 'template' | 'exam';
+    name: string;
+    /** Display labels; codes are authoritative when present. */
+    grade: string;
+    subject: string;
+    gradeCode?: string;
+    courseCode?: string;
+    subjectCode?: string;
+    phaseCode?: 'P' | 'J' | 'S';
+    /** Reference template ID and exam-paper ID, retained without backend requests. */
+    id?: string | number;
+    exampaperId?: string | number;
+    createMode?: 'MANUALLY' | 'IMPORTED' | 'THIRD';
+}
+interface CardHeaderSettings {
+    focusText: boolean;
+    writeKaohao: boolean;
+    missExam: boolean;
+    mifeng: boolean;
+    kaohao: 'school' | 'code';
+    weishu: number;
+}
+
+interface ReferenceOptionData {
+    id?: string | number;
+    key: string;
+    content: string;
+}
+interface ReferenceQuestionData extends Record<string, unknown> {
+    questionId?: string | number;
+    questionPid?: string | number;
+    id?: string | number;
+    questiontypeCode: AtomicType;
+    seq?: string | number;
+    showSeq?: string | number;
+    showSeqs?: (string | number)[] | null;
+    itemShowNames?: (string | number)[] | null;
+    score?: number | null;
+    itemScores?: (number | null)[];
+    itemcount?: number;
+    lessScore?: number;
+    scoreType?: 'LESS_SCORE' | 'ITEM_SCORE';
+    rightAnswers?: number | null;
+    singleScore?: number | null;
+    childNum?: number;
+    content?: string;
+    itemsContent?: ReferenceOptionData[];
+    items?: ReferenceQuestionData[];
+    extension?: Record<string, unknown>;
+}
+interface ReferenceSectionData extends Record<string, unknown> {
+    sectionSeq: string | number;
+    sectionName: string;
+    sectionQuestionType: QuestionType;
+    questionInfolist: ReferenceQuestionData[];
+    content?: string;
+}
+interface ReferencePaperData {
+    sectionInfoList: ReferenceSectionData[];
+    quesTextMap?: Record<string, unknown>;
+}
+
+interface ValidationIssue {
+    code: string;
+    path: string;
+    message: string;
+    blockId?: string;
+    questionId?: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    issues: ValidationIssue[];
+}
+declare class AnswerSheetDataError extends Error {
+    readonly issues: ValidationIssue[];
+    constructor(issues: ValidationIssue[]);
+}
+
+type PhaseCode = 'P' | 'J' | 'S';
+interface GradeOption {
+    value: string;
+    label: string;
+    classify?: PhaseCode;
+}
+interface CourseOption {
+    value: string;
+    label: string;
+    subjectCode?: string;
+    custom?: boolean;
+}
+/** Pass the reference project's permission-filtered options, without fetching inside the plugin. */
+interface AnswerSheetDictionaries {
+    grades?: readonly GradeOption[];
+    gradeCourseMap?: Readonly<Record<string, readonly CourseOption[]>>;
+    courseCodeToSubjectCode?: Readonly<Record<string, string>>;
+    defaultGradeCode?: string;
+    defaultCourseCode?: string;
+}
+
+/** Round-trippable source plus the reference project's sectionInfoList/quesTextMap. */
+type AnswerSheetData = CardDocument & ReferencePaperData;
+type SaveResult = {
+    ok: true;
+    data: AnswerSheetData;
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+type AnswerSheetLayout = Partial<Pick<CardDocument, 'preset' | 'margin' | 'gap' | 'questionCard' | 'scanMarking' | 'halfPoint' | 'choiceDirection' | 'mergeObjective'>> & {
+    /** Reference field aliases; conflicting aliases are rejected. */
+    pageNum?: 1 | 2 | 3;
+    quesCard?: boolean;
+    scoreType?: boolean;
+    choiceType?: boolean;
+    mixOb?: boolean;
+};
+type AnswerSheetInitialization = Pick<CardCreation, 'name' | 'id' | 'exampaperId' | 'createMode'> & {
+    /** Defaults to template, matching the built-in creation dialog. */
+    mode?: CardCreation['mode'];
+    /** Paper preset, margins/gap in mm, and the existing page-layout switches. */
+    layout?: AnswerSheetLayout;
+    header?: Partial<CardHeaderSettings>;
+} & ({
+    gradeCode: string;
+    courseCode: string;
+    subjectCode?: string;
+    grade?: string;
+    subject?: string;
+} | {
+    grade: string;
+    subject: string;
+    gradeCode?: undefined;
+    courseCode?: undefined;
+    subjectCode?: undefined;
+});
+interface AnswerSheetOptions {
+    plugins: readonly AnswerSheetEditorPlugin[];
+    initialValue?: CardDocument;
+    /** Permission-filtered grades/courses. Omit to use reference base subject dictionaries. */
+    dictionaries?: AnswerSheetDictionaries;
+    readOnly?: boolean;
+    uploadImage?: ImageUploadHandler;
+    onChange?: (document: CardDocument) => void;
+    /** The built-in Save button calls this with the same result as save(). */
+    onSave?: (result: SaveResult) => void;
+    onError?: (error: Error) => void;
+}
+interface AnswerSheetInstance {
+    readonly ready: Promise<void>;
+    /** Create a blank card from host settings. Call immediately after mounting to skip the creation dialog. */
+    initialize(options: AnswerSheetInitialization): Promise<void>;
+    /** Draft snapshot, without completeness validation. */
+    getDocument(): CardDocument;
+    /** Restore saved data or a draft, resetting selection and undo history. */
+    load(data: CardDocument | AnswerSheetData): Promise<void>;
+    /** Alias of load(). */
+    setDocument(document: CardDocument): Promise<void>;
+    newDocument(creation: CardCreation): Promise<void>;
+    getReferenceData(): ReferencePaperData;
+    setReferenceData(data: ReferencePaperData | ReferenceSectionData[]): Promise<void>;
+    validate(): Promise<ValidationResult>;
+    /** Waits for input and pagination; failure never contains savable data. */
+    save(): Promise<SaveResult>;
+    setOptions(options: Partial<Omit<AnswerSheetOptions, 'plugins' | 'initialValue'>>): void;
+    focusIssue(issue: ValidationIssue): void;
+    destroy(): void;
+}
+
+/** Framework-free DOM entry. Browser-only code is loaded after an explicit mount. */
+declare function createAnswerSheet(target: string | HTMLElement, options: AnswerSheetOptions): AnswerSheetInstance;
+
+export { AnswerSheetDataError, createAnswerSheet };
+export type { AnswerSheetData, AnswerSheetDictionaries, AnswerSheetEditorPlugin, AnswerSheetInitialization, AnswerSheetInstance, AnswerSheetLayout, AnswerSheetOptions, CardBlock, CardChoiceQuestion, CardChoiceSettings, CardCreation, CardDocument, CardHeaderSettings, CardPaperTitle, CardPreset, CourseOption, GradeOption, ImageUploadHandler, PhaseCode, QuestionType, ReferenceGroup, ReferencePaperData, ReferencePart, ReferenceQuestion, ReferenceSectionData, ReferenceText, RichTextDocument, SaveResult, ValidationIssue, ValidationResult };