@pgcorp/ui-kit 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgcorp/ui-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Typed Vue 3 design system with accessible components, semantic themes, and workbench patterns.",
   "type": "module",
   "types": "./index.ts",

package/src/components/shared/_internal/SHeaderSurface.css

@@ -0,0 +1,98 @@
+@reference "../../../styles/reference.css";
+
+.s-page-header,
+.s-section-header {
+  @apply flex min-w-0 items-start justify-between;
+}
+
+.s-page-header {
+  @apply gap-4 border border-surface-200 bg-surface-0 p-5 shadow-sm;
+  @apply dark:border-surface-700 dark:bg-surface-900;
+  border-radius: var(--radius-sm);
+}
+
+.s-section-header { @apply flex-wrap gap-3; }
+
+.s-page-header[data-appearance='plain'] {
+  @apply border-x-0 border-t-0 bg-transparent px-0 pt-0 shadow-none dark:bg-transparent;
+  border-radius: 0;
+}
+
+.s-page-header[data-size='compact'] { @apply p-4; }
+.s-page-header[data-appearance='plain'][data-size='compact'] { @apply px-0 pt-0; }
+
+.s-page-header[data-appearance='bare'] {
+  @apply border-0 bg-transparent p-0 shadow-none dark:bg-transparent;
+  border-radius: 0;
+}
+
+.s-section-header[data-spacing-after='sm'] { @apply mb-2; }
+.s-section-header[data-spacing-after='md'] { @apply mb-3; }
+.s-section-header[data-divider='true'] { @apply border-b border-surface-200 pb-3 dark:border-surface-700; }
+.s-section-header[data-padding='sm'] { @apply p-2; }
+.s-section-header[data-padding='md'] { @apply p-4; }
+.s-section-header[data-divider='true'][data-padding='sm'] { @apply pb-2; }
+.s-section-header[data-divider='true'][data-padding='md'] { @apply pb-4; }
+
+.s-page-header__copy,
+.s-section-header__copy { @apply min-w-0; }
+.s-section-header__copy { @apply flex-1; }
+
+.s-page-header__eyebrow,
+.s-section-header__eyebrow { @apply text-xs uppercase text-surface-500 dark:text-surface-400; }
+.s-page-header__eyebrow { @apply font-medium; }
+.s-section-header__eyebrow { @apply font-semibold; }
+
+.s-page-header__title,
+.s-section-header__title { @apply m-0 font-semibold text-surface-900 dark:text-surface-50; }
+.s-page-header__title { @apply text-2xl leading-tight; }
+
+.s-page-header__title[data-presentation='assistive'] {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+.s-page-header[data-size='compact'] .s-page-header__title { @apply text-xl; }
+.s-section-header__title { @apply break-words text-base; }
+.s-section-header[data-size='sm'] .s-section-header__title { @apply text-sm; }
+.s-section-header[data-variant='display'] .s-section-header__title {
+  @apply text-xl font-semibold uppercase tracking-[0.22em] text-surface-700 dark:text-surface-200;
+}
+
+.s-page-header__eyebrow + .s-page-header__title,
+.s-section-header__eyebrow + .s-section-header__title { @apply mt-1; }
+
+.s-page-header__description,
+.s-section-header__description,
+.s-section-header__meta { @apply text-surface-500 dark:text-surface-400; }
+.s-page-header__description { @apply mt-2 max-w-4xl text-sm; }
+.s-section-header__description,
+.s-section-header__meta {
+  @apply mt-1 min-w-0 break-words text-xs;
+  overflow-wrap: anywhere;
+}
+
+.s-page-header__actions,
+.s-section-header__trailing,
+.s-section-header__badges,
+.s-section-header__actions { @apply flex min-w-0 flex-wrap items-center justify-end gap-2; }
+.s-page-header__actions { @apply shrink-0; }
+.s-page-header[data-actions-layout='stacked'] { @apply flex-col; }
+
+.s-page-header[data-actions-layout='stacked'] .s-page-header__actions,
+.s-section-header[data-trailing-layout='stacked'] .s-section-header__trailing,
+.s-section-header[data-trailing-layout='stacked'] .s-section-header__actions { @apply w-full justify-start; }
+
+@media (max-width: 639px) {
+  .s-page-header[data-actions-layout='responsive'] { @apply flex-col; }
+
+  .s-page-header[data-actions-layout='responsive'] .s-page-header__actions,
+  .s-section-header[data-trailing-layout='responsive'] .s-section-header__trailing,
+  .s-section-header[data-trailing-layout='responsive'] .s-section-header__actions { @apply w-full justify-start; }
+}

package/src/components/shared/_internal/SHeaderSurface.vue

@@ -0,0 +1,80 @@
+<template>
+  <header
+    :class="kind === 'page' ? 's-page-header' : 's-section-header'"
+    :data-kind="kind"
+    :data-actions-layout="kind === 'page' ? trailingLayout : undefined"
+    :data-trailing-layout="kind === 'section' ? trailingLayout : undefined"
+    :data-appearance="kind === 'page' ? appearance : undefined"
+    :data-size="size"
+    :data-variant="kind === 'section' ? variant : undefined"
+    :data-divider="kind === 'section' && divider ? 'true' : undefined"
+    :data-padding="kind === 'section' ? padding : undefined"
+    :data-spacing-after="kind === 'section' ? spacingAfter : undefined"
+  >
+    <div :class="kind === 'page' ? 's-page-header__copy' : 's-section-header__copy'">
+      <div
+        v-if="eyebrow"
+        :class="kind === 'page' ? 's-page-header__eyebrow' : 's-section-header__eyebrow'"
+      >{{ eyebrow }}</div>
+      <component
+        :is="`h${headingLevel}`"
+        :class="kind === 'page' ? 's-page-header__title' : 's-section-header__title'"
+        :data-presentation="titlePresentation"
+      >{{ title }}</component>
+      <p
+        v-if="description"
+        :class="kind === 'page' ? 's-page-header__description' : 's-section-header__description'"
+      >{{ description }}</p>
+      <p v-if="kind === 'section' && meta" class="s-section-header__meta">{{ meta }}</p>
+    </div>
+
+    <div v-if="hasTrailing" :class="kind === 'page' ? 's-page-header__actions' : 's-section-header__trailing'">
+      <template v-if="kind === 'page'">
+        <slot name="actions" />
+      </template>
+      <template v-else>
+        <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>
+      </template>
+    </div>
+  </header>
+</template>
+
+<script setup lang="ts">
+import { computed, useSlots } from 'vue'
+
+export interface Props {
+  kind: 'page' | 'section'
+  title: string
+  eyebrow?: string | null
+  description?: string | null
+  meta?: string | null
+  headingLevel: 1 | 2 | 3 | 4
+  titlePresentation?: 'visible' | 'assistive'
+  appearance?: 'bare' | 'plain' | 'panel'
+  size: 'compact' | 'default' | 'sm' | 'md'
+  variant?: 'default' | 'display'
+  divider?: boolean
+  padding?: 'none' | 'sm' | 'md'
+  spacingAfter?: 'none' | 'sm' | 'md'
+  trailingLayout: 'responsive' | 'inline' | 'stacked'
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  eyebrow: undefined,
+  description: undefined,
+  meta: undefined,
+  titlePresentation: 'visible',
+  appearance: 'panel',
+  variant: 'default',
+  divider: false,
+  padding: 'none',
+  spacingAfter: 'none',
+})
+const slots = useSlots()
+const hasTrailing = computed(() => props.kind === 'page'
+  ? Boolean(slots.actions)
+  : Boolean(slots.badges || slots.actions))
+</script>
+
+<style lang="postcss" src="./SHeaderSurface.css" scoped></style>

package/src/components/shared/_internal/useRadioGroup.ts

@@ -0,0 +1,106 @@
+import { computed } from 'vue'
+import type { ComponentPublicInstance, ComputedRef, Ref } from 'vue'
+
+import {
+  selectionKeyToken,
+  useSelectionRoving,
+} from './useSelectionRoving'
+import type {
+  SelectionKey,
+  SelectionRovingOption,
+} from './useSelectionRoving'
+
+/** Опция общего radio-group runtime. / An option accepted by the shared radio-group runtime. */
+export type RadioGroupOption<T extends SelectionKey> = SelectionRovingOption<T>
+
+/** ARIA-контракт контейнера radio-group. / ARIA contract for a radio-group container. */
+export interface RadioGroupAriaContract {
+  labelledBy: string
+  describedBy?: string
+  required?: boolean
+  invalid?: boolean
+}
+
+/** Общий runtime-контракт radio-group без визуального представления. / Shared radio-group runtime without presentation ownership. */
+export interface RadioGroupRuntime<T extends SelectionKey> {
+  focusableValue: ComputedRef<T | undefined>
+  groupBindings: (contract: RadioGroupAriaContract) => Record<string, unknown>
+  optionBindings: (option: RadioGroupOption<T>) => Record<string, unknown>
+  optionRef: (value: T) => (element: Element | ComponentPublicInstance | null) => void
+  optionToken: (value: T) => string
+}
+
+function resolveNativeElement(
+  element: Element | ComponentPublicInstance | null,
+): HTMLElement | null {
+  return element instanceof HTMLElement ? element : null
+}
+
+/**
+ * Централизует identity, ARIA, readonly/disabled и roving-focus radio-group.
+ * Centralizes identity, ARIA, readonly/disabled, and roving focus for a radio group.
+ */
+export function useRadioGroup<T extends SelectionKey>(config: {
+  component: string
+  options: ComputedRef<readonly RadioGroupOption<T>[]>
+  selectedValue: Ref<T | null | undefined>
+  disabled: ComputedRef<boolean>
+  readonly: ComputedRef<boolean>
+  update: (value: T) => void
+  orientation?: 'horizontal' | 'vertical' | 'both'
+}): RadioGroupRuntime<T> {
+  const rovingOptions = computed<readonly RadioGroupOption<T>[]>(() => (
+    config.disabled.value
+      ? config.options.value.map((option) => ({ ...option, disabled: true }))
+      : config.options.value
+  ))
+  const select = (value: T): void => {
+    const option = config.options.value.find((candidate) => candidate.value === value)
+    if (config.disabled.value || config.readonly.value || option?.disabled) return
+    config.update(value)
+  }
+  const roving = useSelectionRoving({
+    options: rovingOptions,
+    selectedValue: config.selectedValue,
+    orientation: config.orientation,
+    select,
+    component: config.component,
+  })
+
+  const groupBindings = (contract: RadioGroupAriaContract): Record<string, unknown> => ({
+    role: 'radiogroup',
+    'aria-labelledby': contract.labelledBy,
+    'aria-describedby': contract.describedBy,
+    'aria-required': contract.required || undefined,
+    'aria-invalid': contract.invalid || undefined,
+    'aria-disabled': config.disabled.value || undefined,
+    'aria-readonly': config.readonly.value || undefined,
+  })
+  const optionBindings = (option: RadioGroupOption<T>): Record<string, unknown> => ({
+    type: 'button',
+    role: 'radio',
+    disabled: config.disabled.value || option.disabled,
+    'aria-checked': option.value === config.selectedValue.value,
+    tabindex: option.value === roving.focusableValue.value ? 0 : -1,
+    onClick: () => select(option.value),
+    onKeydown: (event: KeyboardEvent) => roving.handleKeydown(event, option.value),
+  })
+  const optionRef = (value: T) => (
+    element: Element | ComponentPublicInstance | null,
+  ): void => {
+    roving.register(value, resolveNativeElement(element))
+  }
+  const optionToken = (value: T): string => selectionKeyToken(
+    config.component,
+    value,
+    'option.value',
+  )
+
+  return {
+    focusableValue: roving.focusableValue,
+    groupBindings,
+    optionBindings,
+    optionRef,
+    optionToken,
+  }
+}

package/src/components/shared/containers/SPageHeader.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
+import SHeaderSurface from '../_internal/SHeaderSurface.vue'
 
 defineOptions({ inheritAttrs: false })
 
@@ -26,26 +27,18 @@ const ownedAttrs = useOwnedAttrs({ component: 'SPageHeader', owner: 'page header
 </script>
 
 <template>
-  <header
+  <SHeaderSurface
     v-bind="ownedAttrs.bindings()"
-    class="s-page-header"
-    :data-actions-layout="actionsLayout"
-    :data-appearance="appearance"
-    :data-size="size"
+    kind="page"
+    :title="title"
+    :description="description"
+    :eyebrow="eyebrow"
+    :heading-level="headingLevel"
+    :appearance="appearance"
+    :size="size"
+    :trailing-layout="actionsLayout"
+    :title-presentation="titlePresentation"
   >
-    <div class="s-page-header__copy">
-      <div v-if="eyebrow" class="s-page-header__eyebrow">{{ eyebrow }}</div>
-      <component
-        :is="`h${headingLevel}`"
-        class="s-page-header__title"
-        :data-presentation="titlePresentation"
-      >{{ title }}</component>
-      <p v-if="description" class="s-page-header__description">{{ description }}</p>
-    </div>
-    <div v-if="$slots.actions" class="s-page-header__actions">
-      <slot name="actions" />
-    </div>
-  </header>
+    <template v-if="$slots.actions" #actions><slot name="actions" /></template>
+  </SHeaderSurface>
 </template>
-
-<style lang="postcss" src="./SPageHeader.css" scoped></style>

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

@@ -43,11 +43,10 @@
 </template>
 
 <script setup lang="ts">
-import { computed, onMounted, ref, useId, watch } from 'vue'
 import { Check, Minus } from '../../icons/sputnigUiIcons'
 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 })
@@ -83,48 +82,20 @@ const emit = defineEmits<{
 }>()
 const ownedAttrs = useOwnedAttrs({ component: 'SCheckbox', owner: 'native checkbox input' })
 useInteractiveLeafRegistration({ owner: 'SCheckbox' })
-
-const generatedInputId = useId()
-const inputId = computed(() => resolveOptionalDomId(
-  'SCheckbox',
-  'id',
-  props.id,
-  `s-checkbox-${generatedInputId}`,
-))
-const inputEl = ref<HTMLInputElement | null>(null)
-
-const checkedValue = computed(() => {
-  if (typeof props.modelValue !== 'boolean') {
-    throw new TypeError('SCheckbox: modelValue must be boolean')
-  }
-  return props.modelValue
+const {
+  checkedValue,
+  inputEl,
+  inputId,
+  onChange,
+  onClick,
+} = useBinaryInput({
+  owner: 'SCheckbox',
+  inputName: 'checkbox',
+  props,
+  indeterminate: () => props.indeterminate,
+  emitUpdate: (value) => emit('update:modelValue', value),
+  emitClick: (event) => emit('click', event),
 })
-
-function applyIndeterminate(): void {
-  if (inputEl.value) {
-    inputEl.value.indeterminate = props.indeterminate && !checkedValue.value
-  }
-}
-
-onMounted(applyIndeterminate)
-watch([() => props.indeterminate, checkedValue], applyIndeterminate)
-
-function onChange(event: Event): void {
-  if (props.readonly) return
-  const target = event.currentTarget
-  if (!(target instanceof HTMLInputElement)) {
-    throw new TypeError('SCheckbox: change event owner must be the native checkbox 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="./SCheckbox.css" scoped></style>

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

@@ -16,26 +16,19 @@
         :data-columns="columns"
         :data-density="density"
         :data-selection-indicator="selectionIndicator"
-        role="radiogroup"
-        :aria-labelledby="labelId"
-        :aria-describedby="describedBy"
-        :aria-required="required || undefined"
-        :aria-invalid="invalid || undefined"
-        :aria-disabled="disabled || undefined"
-        :aria-readonly="readonly || undefined"
+        v-bind="radioGroup.groupBindings({
+          labelledBy: labelId,
+          describedBy,
+          required,
+          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-choice-card"
-          type="button"
-          :disabled="disabled || option.disabled"
-          :aria-checked="option.value === modelValue"
-          :tabindex="option.value === focusableValue ? 0 : -1"
-          role="radio"
-          @click="select(option.value)"
-          @keydown="roving.handleKeydown($event, option.value)"
+          v-bind="radioGroup.optionBindings(option)"
         >
           <span v-if="option.kicker" class="s-choice-card__kicker">{{ option.kicker }}</span>
           <span class="s-choice-card__title">{{ option.title }}</span>
@@ -83,10 +76,10 @@ export interface Props<T extends PublicSelectionKey = string> {
 
 <script setup lang="ts" generic="T extends SelectionKey = string">
 import { computed } from 'vue'
-import type { ComponentPublicInstance, VNodeChild } from 'vue'
+import type { VNodeChild } 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'
 
@@ -116,30 +109,14 @@ defineSlots<{
 }>()
 const ownedAttrs = useOwnedAttrs({ component: 'SChoiceCards', owner: 'field group' })
 useInteractiveLeafRegistration({ owner: 'SChoiceCards' })
-const select = (value: T): void => {
-  if (props.disabled || props.readonly) return
-  emit('update:modelValue', value)
-}
-const rovingOptions = computed<readonly ChoiceCardOption<T>[]>(() => (
-  props.disabled
-    ? props.options.map((option) => ({ ...option, disabled: true }))
-    : props.options
-))
-const roving = useSelectionRoving({
-  options: rovingOptions,
+const radioGroup = useRadioGroup({
+  options: computed(() => props.options),
   selectedValue: computed(() => props.modelValue),
-  select,
+  disabled: computed(() => props.disabled),
+  readonly: computed(() => props.readonly),
+  update: (value) => emit('update:modelValue', value),
   component: 'SChoiceCards',
 })
-const focusableValue = roving.focusableValue
-const optionToken = (option: ChoiceCardOption<T>): string => selectionKeyToken(
-  'SChoiceCards',
-  option.value,
-  'option.value',
-)
-const resolveNativeElement = (element: Element | ComponentPublicInstance | null): HTMLElement | null => (
-  element instanceof HTMLElement ? element : null
-)
 </script>
 
 <style lang="postcss" src="./SChoiceCards.css" scoped></style>

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

@@ -53,24 +53,12 @@
   @apply flex items-center;
 }
 
-.s-field__required {
-  @apply ml-0.5 text-danger-600 dark:text-danger-400;
-}
-
-.s-field__help,
-.s-field__error {
-  @apply mt-1 min-w-0 whitespace-normal text-xs;
-  overflow-wrap: anywhere;
-}
-
 .s-field__help {
   grid-area: help;
-  @apply text-surface-500 dark:text-surface-400;
 }
 
 .s-field__error {
   grid-area: error;
-  @apply text-danger-600 dark:text-danger-400;
 }
 
 .s-field[data-disabled='true'] .s-field__label,

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

@@ -10,7 +10,7 @@
   >
     <label v-if="hasLabel" :id="labelId" class="s-field__label" :for="controlId">
       <slot name="label">{{ label }}</slot>
-      <span v-if="required" class="s-field__required" aria-hidden="true">*</span>
+      <span v-if="required" :class="['s-field__required', FIELD_REQUIRED_CLASS]" aria-hidden="true">*</span>
     </label>
 
     <div class="s-field__control">
@@ -25,10 +25,10 @@
       />
     </div>
 
-    <p v-if="helpText || $slots.help" :id="helpId" class="s-field__help">
+    <p v-if="helpText || $slots.help" :id="helpId" :class="['s-field__help', FIELD_HELP_CLASS]">
       <slot name="help">{{ helpText }}</slot>
     </p>
-    <p v-if="isInvalid && (errorMessage || $slots.error)" :id="errorId" class="s-field__error">
+    <p v-if="isInvalid && (errorMessage || $slots.error)" :id="errorId" :class="['s-field__error', FIELD_ERROR_CLASS]">
       <slot name="error">{{ errorMessage }}</slot>
     </p>
   </div>
@@ -36,6 +36,12 @@
 
 <script setup lang="ts">
 import { computed, useSlots } from 'vue'
+import {
+  FIELD_ERROR_CLASS,
+  FIELD_HELP_CLASS,
+  FIELD_REQUIRED_CLASS,
+  useFieldSupportingText,
+} from '../../../internal/fieldPresentation'
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
 
 defineOptions({ inheritAttrs: false })
@@ -76,13 +82,11 @@ const ownedAttrs = useOwnedAttrs({ component: 'SField', owner: 'field root' })
 const isInvalid = computed(() => props.invalid)
 const hasLabel = computed(() => Boolean(props.label || slots.label))
 const labelId = computed(() => `${props.controlId}-label`)
-const helpId = computed(() => `${props.controlId}-help`)
-const errorId = computed(() => `${props.controlId}-error`)
-const describedBy = computed(() => {
-  const ids: string[] = []
-  if (props.helpText || slots.help) ids.push(helpId.value)
-  if (isInvalid.value && (props.errorMessage || slots.error)) ids.push(errorId.value)
-  return ids.length > 0 ? ids.join(' ') : undefined
+const fieldId = computed(() => props.controlId)
+const { describedBy, errorId, helpId } = useFieldSupportingText({
+  baseId: fieldId,
+  hasHelp: () => Boolean(props.helpText || slots.help),
+  hasError: () => Boolean(isInvalid.value && (props.errorMessage || slots.error)),
 })
 </script>
 

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

@@ -8,10 +8,6 @@
   @apply mb-2 min-w-0 text-sm font-medium text-surface-700 dark:text-surface-300;
 }
 
-.s-field-group__required {
-  @apply ml-0.5 text-danger-600 dark:text-danger-400;
-}
-
 .s-field-group__controls {
   @apply grid min-w-0 gap-2;
 }
@@ -32,23 +28,9 @@
   @apply grid-cols-4;
 }
 
-.s-field-group__help,
-.s-field-group__error {
-  @apply mt-1 min-w-0 whitespace-normal text-xs;
-  overflow-wrap: anywhere;
-}
-
-.s-field-group__help {
-  @apply text-surface-500 dark:text-surface-400;
-}
-
-.s-field-group__error {
-  @apply text-danger-600 dark:text-danger-400;
-}
-
 .s-field-group[data-disabled='true'] .s-field-group__legend,
 .s-field-group[data-readonly='true'] .s-field-group__legend {
-  @apply text-surface-400 dark:text-surface-500;
+  color: var(--s-field-disabled-foreground);
 }
 
 @media (max-width: 40rem) {

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

@@ -14,7 +14,7 @@
   >
     <legend :id="labelId" class="s-field-group__legend">
       <slot name="label">{{ validatedLabel }}</slot>
-      <span v-if="required" class="s-field-group__required" aria-hidden="true">*</span>
+      <span v-if="required" :class="['s-field-group__required', FIELD_REQUIRED_CLASS]" aria-hidden="true">*</span>
     </legend>
 
     <div class="s-field-group__controls">
@@ -29,10 +29,10 @@
       />
     </div>
 
-    <p v-if="helpText || $slots.help" :id="helpId" class="s-field-group__help">
+    <p v-if="helpText || $slots.help" :id="helpId" :class="['s-field-group__help', FIELD_HELP_CLASS]">
       <slot name="help">{{ helpText }}</slot>
     </p>
-    <p v-if="invalid && (errorMessage || $slots.error)" :id="errorId" class="s-field-group__error">
+    <p v-if="invalid && (errorMessage || $slots.error)" :id="errorId" :class="['s-field-group__error', FIELD_ERROR_CLASS]">
       <slot name="error">{{ errorMessage }}</slot>
     </p>
   </fieldset>
@@ -40,6 +40,12 @@
 
 <script setup lang="ts">
 import { computed, useId, useSlots } from 'vue'
+import {
+  FIELD_ERROR_CLASS,
+  FIELD_HELP_CLASS,
+  FIELD_REQUIRED_CLASS,
+  useFieldSupportingText,
+} from '../../../internal/fieldPresentation'
 import { mergeIdReferences, useOwnedAttrs } from '../../../internal/ownedAttrs'
 import {
   validateBoundedInteger,
@@ -92,13 +98,10 @@ const groupId = computed(() => validateDomId(
 ))
 const labelId = computed(() => `${groupId.value}-legend`)
 const validatedLabel = computed(() => validateNonEmptyString('SFieldGroup', 'label', props.label))
-const helpId = computed(() => `${groupId.value}-help`)
-const errorId = computed(() => `${groupId.value}-error`)
-const describedBy = computed(() => {
-  const ids: string[] = []
-  if (props.helpText || slots.help) ids.push(helpId.value)
-  if (props.invalid && (props.errorMessage || slots.error)) ids.push(errorId.value)
-  return ids.length > 0 ? ids.join(' ') : undefined
+const { describedBy, errorId, helpId } = useFieldSupportingText({
+  baseId: groupId,
+  hasHelp: () => Boolean(props.helpText || slots.help),
+  hasError: () => Boolean(props.invalid && (props.errorMessage || slots.error)),
 })
 const validatedLayout = computed<SFieldGroupLayout>(() => validateExactString(
   'SFieldGroup',