Пользовательские композиты

Пользовательские элементы управления — это исключения, а не альтернативная библиотека компонентов.

Проверка на допуск

Пользовательский элемент управления принимается только когда:

1. PrimeVue не может предоставить или скомпоновать требуемые семантику, взаимодействие и аффорданс.
2. Исключение фиксирует отвергнутые композиции PrimeVue.
3. Оно называет точный сгенерированный контракт соседнего компонента PrimeVue и хэш контракта.
4. Каждое свойство, которое этот контракт соседа классифицирует как shared-runtime, имеет точное сопоставление с источником.
5. Фиксированная утилита допускается только когда контракт соседа классифицирует именно это свойство как platform-invariant.
6. Новая геометрия и поведение изолированы и задокументированы.
7. Доказательства доступности и визуальные доказательства проходят проверку.

Эквивалентность формы данных не есть эквивалентность аффорданса. Многовариантный SelectButton может представлять три значения, но не выглядит и не ведёт себя как скользящий трёхпозиционный переключатель. И наоборот, не выдумывайте prop positions для ToggleSwitch. Создавайте рассмотренного пользовательского соседа только когда требование к аффордансу реально.

Контракт модуля

Храните рассмотренное исключение в wippy-fe.contract.json в корне модуля:

{
  "schemaVersion": "generated-by-selected-contract-tool",
  "exceptions": [
    {
      "id": "module.control.example",
      "source": "src/components/ExampleControl.vue",
      "sourceSha256": "generated-from-source",
      "semanticRole": "documented-role",
      "requiredAffordance": "documented-affordance",
      "rejectedPrimeVueCompositions": [
        {
          "components": ["SelectButton"],
          "reason": "The reviewed sliding affordance cannot be preserved."
        }
      ],
      "visualSibling": {
        "component": "ToggleSwitch",
        "contractId": "primevue.toggleswitch.portable-appearance",
        "contractHash": "generated-from-selected-theme-contract"
      },
      "sharedAppearanceMappings": [
        {
          "contractProperty": "root.width",
          "part": "root",
          "selector": ".example-control",
          "source": {
            "kind": "css-variable",
            "name": "--p-toggleswitch-width"
          }
        }
      ],
      "platformInvariantUtilities": [],
      "moduleLocalProperties": [],
      "accessibilityEvidence": {
        "manifest": ".local/evidence/accessibility-manifest.json",
        "scenarioId": "module.control.example.keyboard",
        "resultId": "module.control.example.keyboard.passed",
        "build": {
          "head": "generated-candidate-commit",
          "trackedFrontendDiffSha256": "generated-diff-hash"
        }
      },
      "visualEvidence": {
        "manifest": ".local/evidence/visual-manifest.json",
        "scenarioId": "module.control.example.light.default",
        "captureId": "module.control.example.light.default.component",
        "build": {
          "head": "generated-candidate-commit",
          "trackedFrontendDiffSha256": "generated-diff-hash"
        }
      }
    }
  ]
}

Показанные значения — заполнители схемы, а не валидные доказательства. Полное сопоставление генерируется из выбранного контракта соседа; выдержка из одной строки сама по себе не является валидным исключением. Инструменты генерируют хэши источника и контракта. Изменившийся хэш источника или хэш контракта соседа делает рассмотрение недействительным.

Эта страница определяет нормативные поля; она не является JSON Schema, и чекер документации лишь доказывает, что этот пример сохраняет требуемую форму. wippy-fe-compliance валидирует реальный контракт модуля относительно выбранного манифеста темы, проверяет хэши и полный набор свойств и убеждается, что каждая ссылка на доказательство разрешается в названный успешный результат или захват из той же кандидатной сборки. Доказательства доступности связывают sourceSha256 компонента, хэшированные файлы, нулевое количество неожиданных ошибок в консоли и успешный результат. Визуальные доказательства связывают канонические файлы до/после/diff, хэши, пересчитанные метрики и вердикт, а также соответствующую кандидатную сборку. Строка, отсутствующий файл, отсутствующие сценарий/результат/захват, устаревший хэш сборки, pending или нерассмотренный результат не удовлетворяют требованию к доказательствам.

platformInvariantUtilities и moduleLocalProperties могут быть пустыми. Никогда не выдумывайте gap-2, w-10, rounded-md или другую фиксированную утилиту лишь для того, чтобы поле контракта не было пустым. В частности, сосед ToggleSwitch не может переклассифицировать ширину, высоту, радиус, геометрию фокуса или анимацию как инвариантные, когда выбранный контракт соседа классифицирует эти свойства как shared-runtime.

Манифест соседа классифицирует свойства как:

• shared-runtime: каждый пользовательский сосед сопоставляет и потребляет опубликованный токен или семантическую утилиту с runtime-подложкой.
• platform-invariant: фиксированное значение допускается только для этого конкретного свойства.
• implementation-private: внутренняя механика PrimeVue не становится требованием для пользовательского соседа.

Если требуемой runtime-семантики не существует, сначала исправьте общий контракт темы. Никогда не копируйте текущие размеры соседа и не выдумывайте имя токена.

sharedAppearanceMappings исчерпывающ, а не иллюстративен: он содержит ровно одно сопоставление для каждого свойства shared-runtime в выбранном контракте соседа, никаких дополнительных идентификаторов свойств, часть контракта, стабильный селектор модуля и точные опубликованные вид и имя источника. Инструменты проверки соответствия используют селектор, часть, CSS-свойство и опубликованный источник, чтобы структурно доказать сопоставление через PostCSS; имя токена в комментарии или несвязанном селекторе не засчитывается. Сопоставление на основе Tailwind также фиксирует уникальные, точные utilityClasses; после нормализации этот набор должен совпадать с набором источников выбранного контракта соседа. platformInvariantUtilities содержит записи вида { "contractProperty": "...", "utility": "..." }, утилита в которых совпадает с источником выбранного контракта соседа. moduleLocalProperties, если он непуст, содержит структурированные идентификаторы свойств и причины рассмотрения, а не свободный набор CSS.

Общий пакет @wippy-fe/ui не создаётся ради одного исключения. Продвижение становится возможным только после того, как второй независимый потребитель докажет те же требования к поведению и переносимости.