@pgcorp/ui-kit 0.5.0 → 0.6.0

package/src/components/shared/controls/SFieldLabel.css

@@ -9,4 +9,3 @@
 .s-field-label[data-size='md'] { @apply text-sm; }
 .s-field-label[data-align='end'] { @apply text-right; }
 .s-field-label[data-disabled='true'] { @apply text-surface-400 dark:text-surface-500; }
-.s-field-label__required { @apply ml-0.5 text-danger-600 dark:text-danger-400; }

package/src/components/shared/controls/SFieldLabel.vue

@@ -8,12 +8,13 @@
     :data-disabled="disabled || undefined"
   >
     <slot />
-    <span v-if="required" class="s-field-label__required" aria-hidden="true">*</span>
+    <span v-if="required" :class="['s-field-label__required', FIELD_REQUIRED_CLASS]" aria-hidden="true">*</span>
   </label>
 </template>
 
 <script setup lang="ts">
 import type { VNodeChild } from 'vue'
+import { FIELD_REQUIRED_CLASS } from '../../../internal/fieldPresentation'
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
 
 defineOptions({ inheritAttrs: false })

package/src/components/shared/controls/SSegmentedControl.vue

@@ -17,27 +17,21 @@
         :data-option-wrap="optionWrap"
         :data-invalid="group.invalid || undefined"
         :data-readonly="group.readonly || undefined"
-        role="radiogroup"
-        :aria-labelledby="group.labelId"
-        :aria-describedby="group.describedBy"
-        :aria-invalid="group.invalid || undefined"
-        :aria-required="group.required || undefined"
-        :aria-readonly="group.readonly || undefined"
+        v-bind="radioGroup.groupBindings({
+          labelledBy: group.labelId,
+          describedBy: group.describedBy,
+          required: group.required,
+          invalid: group.invalid,
+        })"
       >
         <button
           v-for="option in options"
-          :key="optionToken(option)"
-          :ref="(element) => roving.register(option.value, resolveNativeElement(element))"
+          :key="radioGroup.optionToken(option.value)"
+          :ref="radioGroup.optionRef(option.value)"
           class="s-segmented-control__item"
           :data-size="size"
-          type="button"
-          :aria-checked="option.value === modelValue"
-          :disabled="group.disabled || option.disabled"
-          role="radio"
-          :tabindex="option.value === focusableValue ? 0 : -1"
           :title="option.title"
-          @click="selectOption(option)"
-          @keydown="roving.handleKeydown($event, option.value)"
+          v-bind="radioGroup.optionBindings(option)"
         >{{ option.label }}</button>
       </div>
     </template>
@@ -74,10 +68,9 @@ export interface Props<T extends PublicSelectionKey = string> {
 
 <script setup lang="ts" generic="T extends SelectionKey = string">
 import { computed } from 'vue'
-import type { ComponentPublicInstance } from 'vue'
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
 import { useInteractiveLeafRegistration } from '../../../internal/passiveContentContract'
-import { selectionKeyToken, useSelectionRoving } from '../_internal/useSelectionRoving'
+import { useRadioGroup } from '../_internal/useRadioGroup'
 import type { SelectionKey } from '../_internal/useSelectionRoving'
 import SFieldGroup from './SFieldGroup.vue'
 
@@ -100,35 +93,14 @@ const emit = defineEmits<{
 }>()
 const ownedAttrs = useOwnedAttrs({ component: 'SSegmentedControl', owner: 'field group root' })
 useInteractiveLeafRegistration({ owner: 'SSegmentedControl' })
-
-function selectOption(option: SegmentedControlOption<T>): void {
-  if (props.disabled || props.readonly || option.disabled) {
-    return
-  }
-  emit('update:modelValue', option.value)
-}
-
-const rovingOptions = computed(() => props.options.map((option) => ({
-  value: option.value,
-  disabled: props.disabled || option.disabled,
-})))
-const roving = useSelectionRoving({
-  options: rovingOptions,
+const radioGroup = useRadioGroup({
+  options: computed(() => props.options),
   selectedValue: computed(() => props.modelValue),
-  select: (value) => {
-    if (!props.disabled && !props.readonly) emit('update:modelValue', value)
-  },
+  disabled: computed(() => props.disabled),
+  readonly: computed(() => props.readonly),
+  update: (value) => emit('update:modelValue', value),
   component: 'SSegmentedControl',
 })
-const focusableValue = roving.focusableValue
-const optionToken = (option: SegmentedControlOption<T>): string => selectionKeyToken(
-  'SSegmentedControl',
-  option.value,
-  'option.value',
-)
-const resolveNativeElement = (element: Element | ComponentPublicInstance | null): HTMLElement | null => (
-  element instanceof HTMLElement ? element : null
-)
 </script>
 
 <style lang="postcss" src="./SSegmentedControl.css" scoped></style>

package/src/components/shared/controls/SSwitch.vue

@@ -13,6 +13,7 @@
     <template #default="field">
       <span class="s-switch-control">
         <input
+          ref="inputEl"
           v-bind="ownedAttrs.bindings()"
           :id="field.controlId"
           type="checkbox"
@@ -37,10 +38,9 @@
 </template>
 
 <script setup lang="ts">
-import { computed, useId } from 'vue'
 import { mergeIdReferences, useOwnedAttrs } from '../../../internal/ownedAttrs'
 import { useInteractiveLeafRegistration } from '../../../internal/passiveContentContract'
-import { resolveOptionalDomId } from '../../../internal/runtimeContract'
+import { useBinaryInput } from '../../../internal/useBinaryInput'
 import SField from './SField.vue'
 
 defineOptions({ inheritAttrs: false })
@@ -73,37 +73,19 @@ const emit = defineEmits<{
 }>()
 const ownedAttrs = useOwnedAttrs({ component: 'SSwitch', owner: 'native switch input' })
 useInteractiveLeafRegistration({ owner: 'SSwitch' })
-
-const generatedInputId = useId()
-const inputId = computed(() => resolveOptionalDomId(
-  'SSwitch',
-  'id',
-  props.id,
-  `s-switch-${generatedInputId}`,
-))
-const checkedValue = computed(() => {
-  if (typeof props.modelValue !== 'boolean') {
-    throw new TypeError('SSwitch: modelValue must be boolean')
-  }
-  return props.modelValue
+const {
+  checkedValue,
+  inputEl,
+  inputId,
+  onChange,
+  onClick,
+} = useBinaryInput({
+  owner: 'SSwitch',
+  inputName: 'switch',
+  props,
+  emitUpdate: (value) => emit('update:modelValue', value),
+  emitClick: (event) => emit('click', event),
 })
-
-function onChange(event: Event): void {
-  if (props.readonly) return
-  const target = event.currentTarget
-  if (!(target instanceof HTMLInputElement)) {
-    throw new TypeError('SSwitch: change event owner must be the native switch input')
-  }
-  emit('update:modelValue', target.checked)
-}
-
-function onClick(event: MouseEvent): void {
-  if (props.readonly) {
-    event.preventDefault()
-    return
-  }
-  emit('click', event)
-}
 </script>
 
 <style lang="postcss" src="./SSwitch.css" scoped></style>

package/src/components/shared/data-display/SBadge.vue

@@ -1,42 +1,56 @@
 <template>
   <span
-    v-bind="ownedAttrs.bindings()"
+    v-bind="{ ...ownedAttrs.bindings(), ...surfaceBindings }"
     class="s-badge"
-    :class="{ 's-badge--dot': dot }"
-    :data-severity="severity"
-    :data-size="size"
-    :data-max-width="maxWidth"
-    :data-truncate="truncate || undefined"
-    :data-icon-motion="iconMotion"
   >
     <template v-if="!dot">
-      <span v-if="leadingIcon" class="s-badge__icon" aria-hidden="true">
-        <component :is="leadingIcon" class="s-badge__icon-graphic" />
+      <span v-if="leadingIcon" :class="PILL_ICON_CLASS" aria-hidden="true">
+        <component
+          :is="leadingIcon"
+          :class="[
+            PILL_ICON_GRAPHIC_CLASS,
+            { [PILL_ICON_SPIN_CLASS]: iconMotion === 'spin' },
+          ]"
+        />
+      </span>
+      <span :class="[PILL_LABEL_CLASS, { [PILL_LABEL_TRUNCATE_CLASS]: truncate }]">
+        <slot />
       </span>
-      <span class="s-badge__label"><slot /></span>
     </template>
   </span>
 </template>
 
 <script setup lang="ts">
-import type { Component } from 'vue';
+import { computed, type Component } from 'vue';
 import { useOwnedAttrs } from '../../../internal/ownedAttrs';
+import {
+  PILL_ICON_CLASS,
+  PILL_ICON_GRAPHIC_CLASS,
+  PILL_ICON_SPIN_CLASS,
+  PILL_LABEL_CLASS,
+  PILL_LABEL_TRUNCATE_CLASS,
+  resolvePillSurfaceBindings,
+  type PillSurfaceIconMotion,
+  type PillSurfaceMaxWidth,
+  type PillSurfaceSeverity,
+  type PillSurfaceSize,
+} from '../../../internal/pillSurface';
 
 defineOptions({ inheritAttrs: false });
 
-export type BadgeSeverity = 'primary' | 'secondary' | 'success' | 'info' | 'warn' | 'danger' | 'contrast';
+export type BadgeSeverity = PillSurfaceSeverity;
 
 export interface Props {
   severity?: BadgeSeverity;
   dot?: boolean;
-  size?: 'xs' | 'sm' | 'md';
+  size?: PillSurfaceSize;
   leadingIcon?: Component;
-  iconMotion?: 'static' | 'spin';
+  iconMotion?: PillSurfaceIconMotion;
   truncate?: boolean;
-  maxWidth?: 'none' | 'sm' | 'md';
+  maxWidth?: PillSurfaceMaxWidth;
 }
 
-withDefaults(defineProps<Props>(), {
+const props = withDefaults(defineProps<Props>(), {
   severity: 'secondary',
   dot: false,
   size: 'md',
@@ -47,6 +61,15 @@ withDefaults(defineProps<Props>(), {
 });
 
 const ownedAttrs = useOwnedAttrs({ component: 'SBadge', owner: 'badge root' });
+const surfaceBindings = computed(() => resolvePillSurfaceBindings('SBadge', {
+  kind: 'badge',
+  severity: props.severity,
+  size: props.size,
+  dot: props.dot,
+  closable: false,
+  disabled: false,
+  truncate: props.truncate,
+  maxWidth: props.maxWidth,
+  iconMotion: props.iconMotion,
+}));
 </script>
-
-<style lang="postcss" src="./SBadge.css" scoped></style>

package/src/components/shared/data-display/SChip.vue

@@ -1,16 +1,12 @@
 <template>
   <span
-    v-bind="ownedAttrs.bindings()"
+    v-bind="{ ...ownedAttrs.bindings(), ...surfaceBindings }"
     class="s-chip"
-    :data-severity="validatedSeverity"
-    :data-size="validatedSize"
-    :data-closable="closable || undefined"
-    :data-disabled="disabled || undefined"
   >
-    <span v-if="leadingIcon" class="s-chip__icon" aria-hidden="true">
-      <component :is="leadingIcon" class="s-chip__icon-graphic" />
+    <span v-if="leadingIcon" :class="PILL_ICON_CLASS" aria-hidden="true">
+      <component :is="leadingIcon" :class="PILL_ICON_GRAPHIC_CLASS" />
     </span>
-    <span class="s-chip__label">{{ validatedLabel }}</span>
+    <span :class="[PILL_LABEL_CLASS, PILL_LABEL_TRUNCATE_CLASS]">{{ validatedLabel }}</span>
     <SButton
       v-if="closable"
       label=""
@@ -34,6 +30,13 @@
 import { computed, type Component } from 'vue'
 import { X } from '../../icons/sputnigUiIcons'
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
+import {
+  PILL_ICON_CLASS,
+  PILL_ICON_GRAPHIC_CLASS,
+  PILL_LABEL_CLASS,
+  PILL_LABEL_TRUNCATE_CLASS,
+  resolvePillSurfaceBindings,
+} from '../../../internal/pillSurface'
 import {
   validateBoolean,
   validateExactString,
@@ -80,6 +83,17 @@ const validatedSeverity = computed(() => validateExactString(
 const validatedSize = computed(() => validateExactString(
   'SChip', 'size', props.size, ['sm', 'md'] as const,
 ))
+const surfaceBindings = computed(() => resolvePillSurfaceBindings('SChip', {
+  kind: 'chip',
+  severity: validatedSeverity.value,
+  size: validatedSize.value,
+  dot: false,
+  closable: props.closable,
+  disabled: props.disabled,
+  truncate: true,
+  maxWidth: 'none',
+  iconMotion: 'static',
+}))
 const resolvedCloseLabel = computed(() => {
   validateBoolean('SChip', 'closable', props.closable)
   validateBoolean('SChip', 'disabled', props.disabled)
@@ -88,5 +102,3 @@ const resolvedCloseLabel = computed(() => {
     : validateNonEmptyString('SChip', 'closeLabel', props.closeLabel)
 })
 </script>
-
-<style lang="postcss" src="./SChip.css" scoped></style>

package/src/components/shared/data-display/SSectionHeader.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
+import SHeaderSurface from '../_internal/SHeaderSurface.vue'
 
 defineOptions({ inheritAttrs: false })
 
@@ -32,27 +33,22 @@ const ownedAttrs = useOwnedAttrs({ component: 'SSectionHeader', owner: 'section
 </script>
 
 <template>
-  <header
+  <SHeaderSurface
     v-bind="ownedAttrs.bindings()"
-    class="s-section-header"
-    :data-size="size"
-    :data-variant="variant"
-    :data-divider="divider || undefined"
-    :data-padding="padding"
-    :data-spacing-after="spacingAfter"
-    :data-trailing-layout="trailingLayout"
+    kind="section"
+    :title="title"
+    :eyebrow="eyebrow"
+    :description="description"
+    :meta="meta"
+    :heading-level="headingLevel"
+    :size="size"
+    :variant="variant"
+    :divider="divider"
+    :padding="padding"
+    :spacing-after="spacingAfter"
+    :trailing-layout="trailingLayout"
   >
-    <div class="s-section-header__copy">
-      <div v-if="eyebrow" class="s-section-header__eyebrow">{{ eyebrow }}</div>
-      <component :is="`h${headingLevel}`" class="s-section-header__title">{{ title }}</component>
-      <p v-if="description" class="s-section-header__description">{{ description }}</p>
-      <p v-if="meta" class="s-section-header__meta">{{ meta }}</p>
-    </div>
-    <div v-if="$slots.badges || $slots.actions" class="s-section-header__trailing">
-      <div v-if="$slots.badges" class="s-section-header__badges"><slot name="badges" /></div>
-      <div v-if="$slots.actions" class="s-section-header__actions"><slot name="actions" /></div>
-    </div>
-  </header>
+    <template v-if="$slots.badges" #badges><slot name="badges" /></template>
+    <template v-if="$slots.actions" #actions><slot name="actions" /></template>
+  </SHeaderSurface>
 </template>
-
-<style lang="postcss" src="./SSectionHeader.css" scoped></style>

package/src/components/shared/database/SDataGrid.vue

@@ -8,6 +8,9 @@
     no-content-padding
     content-layout="block"
     surface-overflow="clip"
+    :surface-tone="validatedPresentation === 'embedded' ? 'transparent' : 'default'"
+    :surface-border="validatedPresentation === 'embedded' ? 'none' : 'default'"
+    :surface-radius="validatedPresentation === 'embedded' ? 'none' : 'default'"
   >
     <template v-if="$slots.actions" #actions>
       <slot
@@ -113,6 +116,8 @@ export interface SDataGridProps<Key extends SDataGridColumnKey = SDataGridColumn
   emptyMessage?: string
   selectedRowId?: string
   maxHeight?: ScrollableViewportMaxBlockSize
+  /** Surface chrome для самостоятельного или вложенного grid. / Surface chrome for a standalone or embedded grid. */
+  presentation?: 'panel' | 'embedded'
   /** Accessible name без visible title. / Accessible name when there is no visible title. */
   ariaLabel?: string
   /** DOM id external visible title. / DOM id of an external visible title. */
@@ -168,6 +173,7 @@ const props = withDefaults(defineProps<SDataGridProps<ColumnKey>>(), {
   emptyMessage: 'Нет строк для отображения',
   selectedRowId: undefined,
   maxHeight: 'none',
+  presentation: 'panel',
   ariaLabel: undefined,
   ariaLabelledby: undefined,
 })
@@ -185,6 +191,7 @@ const CELL_KINDS = ['text', 'number', 'boolean', 'json', 'datetime', 'binary'] a
 const COLUMN_ALIGNMENTS = ['left', 'center', 'right'] as const
 const ROW_STATES = ['clean', 'inserted', 'updated', 'deleted'] as const
 const COMMIT_SOURCES = ['draft', 'value'] as const
+const PRESENTATIONS = ['panel', 'embedded'] as const
 
 function assertReadonlyArray(value: unknown, coordinate: string): asserts value is readonly unknown[] {
   if (Array.isArray(value)) return
@@ -335,6 +342,12 @@ const resolvedAccessibleName = computed(() => {
 const validatedLoading = computed(() => validateBoolean('SDataGrid', 'loading', props.loading))
 const validatedDisabled = computed(() => validateBoolean('SDataGrid', 'disabled', props.disabled))
 const validatedReadOnly = computed(() => validateBoolean('SDataGrid', 'readOnly', props.readOnly))
+const validatedPresentation = computed(() => validateExactString(
+  'SDataGrid',
+  'presentation',
+  props.presentation,
+  PRESENTATIONS,
+))
 const validatedMaxHeight = computed(() => validateScrollableViewportMaxBlockSize(
   'SDataGrid',
   'maxHeight',

package/src/internal/fieldPresentation.ts

@@ -0,0 +1,28 @@
+import { computed, type ComputedRef } from 'vue'
+
+export const FIELD_REQUIRED_CLASS = 'ml-0.5 text-danger-600 dark:text-danger-400'
+export const FIELD_SUPPORT_CLASS = 'mt-1 min-w-0 whitespace-normal text-xs [overflow-wrap:anywhere]'
+export const FIELD_HELP_CLASS = `${FIELD_SUPPORT_CLASS} text-surface-500 dark:text-surface-400`
+export const FIELD_ERROR_CLASS = `${FIELD_SUPPORT_CLASS} text-danger-600 dark:text-danger-400`
+
+export interface FieldSupportingTextOptions {
+  readonly baseId: ComputedRef<string>
+  readonly hasHelp: () => boolean
+  readonly hasError: () => boolean
+}
+
+/**
+ * Владеет exact ID и aria-describedby contract для help/error у field и fieldset.
+ * Owns the exact help/error ID and aria-describedby contract for fields and fieldsets.
+ */
+export function useFieldSupportingText(options: FieldSupportingTextOptions) {
+  const helpId = computed(() => `${options.baseId.value}-help`)
+  const errorId = computed(() => `${options.baseId.value}-error`)
+  const describedBy = computed(() => {
+    const ids: string[] = []
+    if (options.hasHelp()) ids.push(helpId.value)
+    if (options.hasError()) ids.push(errorId.value)
+    return ids.length > 0 ? ids.join(' ') : undefined
+  })
+  return { describedBy, errorId, helpId } as const
+}

package/src/internal/pillSurface.ts

@@ -0,0 +1,92 @@
+import {
+  validateBoolean,
+  validateExactString,
+} from './runtimeContract'
+
+const PILL_KINDS = ['badge', 'chip'] as const
+const PILL_SEVERITIES = [
+  'primary',
+  'secondary',
+  'success',
+  'info',
+  'warn',
+  'danger',
+  'contrast',
+] as const
+const PILL_SIZES = ['xs', 'sm', 'md'] as const
+const PILL_MAX_WIDTHS = ['none', 'sm', 'md'] as const
+const PILL_ICON_MOTIONS = ['static', 'spin'] as const
+
+export type PillSurfaceKind = typeof PILL_KINDS[number]
+export type PillSurfaceSeverity = typeof PILL_SEVERITIES[number]
+export type PillSurfaceSize = typeof PILL_SIZES[number]
+export type PillSurfaceMaxWidth = typeof PILL_MAX_WIDTHS[number]
+export type PillSurfaceIconMotion = typeof PILL_ICON_MOTIONS[number]
+
+export const PILL_ICON_CLASS = 's-pill-icon inline-flex h-[var(--s-pill-icon-size)] w-[var(--s-pill-icon-size)] shrink-0 items-center justify-center'
+export const PILL_ICON_GRAPHIC_CLASS = 's-pill-icon-graphic h-full w-full'
+export const PILL_ICON_SPIN_CLASS = 'animate-spin'
+export const PILL_LABEL_CLASS = 's-pill-label min-w-0'
+export const PILL_LABEL_TRUNCATE_CLASS = 'overflow-hidden text-ellipsis whitespace-nowrap'
+
+export interface PillSurfaceContract {
+  kind: PillSurfaceKind
+  severity: PillSurfaceSeverity
+  size: PillSurfaceSize
+  dot: boolean
+  closable: boolean
+  disabled: boolean
+  truncate: boolean
+  maxWidth: PillSurfaceMaxWidth
+  iconMotion: PillSurfaceIconMotion
+}
+
+export interface PillSurfaceBindings {
+  'data-s-pill-surface': PillSurfaceKind
+  'data-s-feedback-tone': PillSurfaceSeverity
+  'data-s-pill-size': PillSurfaceSize
+  'data-s-pill-dot'?: 'true'
+  'data-s-pill-closable'?: 'true'
+  'data-s-pill-disabled'?: 'true'
+  'data-s-pill-truncate'?: 'true'
+  'data-s-pill-max-width'?: Exclude<PillSurfaceMaxWidth, 'none'>
+  'data-s-pill-icon-motion'?: Exclude<PillSurfaceIconMotion, 'static'>
+}
+
+/**
+ * Создаёт exact bindings единого pill/feedback presentation owner.
+ * Creates exact bindings for the canonical pill/feedback presentation owner.
+ */
+export function resolvePillSurfaceBindings(
+  owner: 'SBadge' | 'SChip',
+  contract: PillSurfaceContract,
+): PillSurfaceBindings {
+  const kind = validateExactString(owner, 'pill kind', contract.kind, PILL_KINDS)
+  const severity = validateExactString(owner, 'severity', contract.severity, PILL_SEVERITIES)
+  const size = validateExactString(owner, 'size', contract.size, PILL_SIZES)
+  const maxWidth = validateExactString(owner, 'maxWidth', contract.maxWidth, PILL_MAX_WIDTHS)
+  const iconMotion = validateExactString(owner, 'iconMotion', contract.iconMotion, PILL_ICON_MOTIONS)
+  const dot = validateBoolean(owner, 'dot', contract.dot)
+  const closable = validateBoolean(owner, 'closable', contract.closable)
+  const disabled = validateBoolean(owner, 'disabled', contract.disabled)
+  const truncate = validateBoolean(owner, 'truncate', contract.truncate)
+
+  if (kind === 'chip' && dot) {
+    throw new TypeError('SChip: dot presentation не поддерживается. / SChip: dot presentation is not supported.')
+  }
+  if (kind === 'badge' && closable) {
+    throw new TypeError('SBadge: closable presentation не поддерживается. / SBadge: closable presentation is not supported.')
+  }
+
+  return {
+    'data-s-pill-surface': kind,
+    'data-s-feedback-tone': severity,
+    'data-s-pill-size': size,
+    ...(dot ? { 'data-s-pill-dot': 'true' as const } : {}),
+    ...(closable ? { 'data-s-pill-closable': 'true' as const } : {}),
+    ...(disabled ? { 'data-s-pill-disabled': 'true' as const } : {}),
+    ...(truncate ? { 'data-s-pill-truncate': 'true' as const } : {}),
+    ...(maxWidth === 'none' ? {} : { 'data-s-pill-max-width': maxWidth }),
+    ...(iconMotion === 'static' ? {} : { 'data-s-pill-icon-motion': iconMotion }),
+  }
+}

package/src/internal/useBinaryInput.ts

@@ -0,0 +1,76 @@
+import { computed, onMounted, ref, useId, watch } from 'vue'
+
+import { resolveOptionalDomId } from './runtimeContract'
+
+export type BinaryInputOwner = 'SCheckbox' | 'SSwitch'
+
+export interface BinaryInputModelContract {
+  readonly modelValue: boolean
+  readonly readonly: boolean
+  readonly id?: string
+}
+
+export interface BinaryInputOptions {
+  readonly owner: BinaryInputOwner
+  readonly inputName: 'checkbox' | 'switch'
+  readonly props: BinaryInputModelContract
+  readonly indeterminate?: () => boolean
+  readonly emitUpdate: (value: boolean) => void
+  readonly emitClick: (event: MouseEvent) => void
+}
+
+/**
+ * Единый runtime owner controlled binary input: identity, value, readonly и native events.
+ * Canonical runtime owner for controlled binary input identity, value, readonly, and native events.
+ */
+export function useBinaryInput(options: BinaryInputOptions) {
+  const generatedInputId = useId()
+  const inputId = computed(() => resolveOptionalDomId(
+    options.owner,
+    'id',
+    options.props.id,
+    `s-${options.inputName}-${generatedInputId}`,
+  ))
+  const inputEl = ref<HTMLInputElement | null>(null)
+  const checkedValue = computed(() => {
+    if (typeof options.props.modelValue !== 'boolean') {
+      throw new TypeError(`${options.owner}: modelValue must be boolean`)
+    }
+    return options.props.modelValue
+  })
+
+  const applyIndeterminate = (): void => {
+    if (inputEl.value) {
+      inputEl.value.indeterminate = (options.indeterminate?.() ?? false) && !checkedValue.value
+    }
+  }
+  onMounted(applyIndeterminate)
+  watch([options.indeterminate ?? (() => false), checkedValue], applyIndeterminate)
+
+  const onChange = (event: Event): void => {
+    if (options.props.readonly) return
+    const target = event.currentTarget
+    if (!(target instanceof HTMLInputElement)) {
+      throw new TypeError(
+        `${options.owner}: change event owner must be the native ${options.inputName} input`,
+      )
+    }
+    options.emitUpdate(target.checked)
+  }
+
+  const onClick = (event: MouseEvent): void => {
+    if (options.props.readonly) {
+      event.preventDefault()
+      return
+    }
+    options.emitClick(event)
+  }
+
+  return {
+    checkedValue,
+    inputEl,
+    inputId,
+    onChange,
+    onClick,
+  } as const
+}