Snapshot of main at 9f39a6e1e (2026-11-02)

app/Polls/Contracts/QuestionType.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace App\Polls\Contracts;
+
+use Illuminate\Support\Collection;
+
+/**
+ * A poll question type (yes/no, multi-select, ranking...).
+ *
+ * Adding a type: implement this interface (usually by extending AbstractQuestionType),
+ * add the editor/input/results partials in resources/views/polls/types/{key}/
+ * and register the class under 'polls.question_types' in the platform config.
+ *
+ * An answer arrives from the poll form as ['value' => mixed, 'text' => ?string].
+ *
+ * Partials receive:
+ * - editor:  $type, $settings, $prefix ('questions.{index}.settings'), $index, $locale.
+ *            List items (options, slots) are added/removed/moved through the editor
+ *            component's addListItem($index, $list), removeListItem($index, $list, $i)
+ *            and moveListItem($index, $list, $i, $direction) methods.
+ * - input:   $type, $question, $settings, $prefix ('answers.{question id}'), $locale.
+ * - results: $type, $question, $settings, $summary (from aggregate()), $locale.
+ */
+interface QuestionType
+{
+    /** Registry key, stored in poll_questions.type. */
+    public function key(): string;
+
+    /** Translated name shown in the poll editor. */
+    public function label(): string;
+
+    /** Settings a new question of this type starts with. */
+    public function defaultSettings(): array;
+
+    /**
+     * Validation rules for the settings in the poll editor.
+     *
+     * @param string $prefix e.g. 'questions.0.settings'
+     * @param array $settings the settings being validated (some limits depend on them)
+     */
+    public function settingsRules(string $prefix, array $settings): array;
+
+    /**
+     * A new item for a settings list, e.g. an option or a date slot.
+     */
+    public function newListItem(string $list): array;
+
+    /**
+     * Validation rules for one answer in the poll form.
+     *
+     * @param string $prefix e.g. 'answers.12'
+     */
+    public function answerRules(string $prefix, array $settings, bool $required): array;
+
+    /**
+     * Custom validation messages for the rules of answerRules(), keyed like Laravel's messages.
+     *
+     * @param string $prefix e.g. 'answers.12'
+     */
+    public function answerMessages(string $prefix, array $settings): array;
+
+    /**
+     * Turn a validated answer into what is stored.
+     *
+     * @return array{value: mixed, text: ?string}
+     */
+    public function normalize(array $answer, array $settings): array;
+
+    /**
+     * Summarise the stored answers of one question for the results view.
+     *
+     * @param Collection<int, \App\Models\PollAnswer> $answers
+     */
+    public function aggregate(Collection $answers, array $settings): array;
+
+    /**
+     * One stored answer as readable text, e.g. for the CSV export.
+     */
+    public function answerToText(mixed $value, ?string $text, array $settings, ?string $locale = null): string;
+
+    /** Blade partial for the settings in the poll editor. */
+    public function editorView(): string;
+
+    /** Blade partial for answering in the poll form. */
+    public function inputView(): string;
+
+    /** Blade partial for the results. */
+    public function resultsView(): string;
+}