feat: Implement OnyxForm with disabled state injection

.changeset/beige-swans-add.md

@@ -0,0 +1,5 @@
+---
+"sit-onyx": minor
+---
+
+Implement OnyxForm which allows setting of disabled state for all child form elements

.changeset/sharp-news-bake.md

@@ -0,0 +1,5 @@
+---
+"@sit-onyx/storybook-utils": minor
+---
+
+New createSymbolArgTypeEnhancer which adds description text to symbols used as default props

packages/sit-onyx/.storybook/formInjected.ts

@@ -0,0 +1,7 @@
+import { createSymbolArgTypeEnhancer } from "@sit-onyx/storybook-utils";
+
+export const enhanceFormInjectedSymbol = createSymbolArgTypeEnhancer(
+ "FORM_INJECTED_SYMBOL",
+ "If no value (or `undefined`) is provided, `FORM_INJECTED_SYMBOL` is the internal default value for this prop.\n" +
+ "In that case the props value will be derived from it's parent form (if it exists).\n",
+);

packages/sit-onyx/.storybook/managed.ts

@@ -1,51 +1,9 @@
-import { walkTree } from "@sit-onyx/storybook-utils";
-import type {
- ArgTypesEnhancer,
- InputType,
- SBType,
- StrictInputType,
-} from "storybook/internal/types";
-
-const SB_TYPE_CONTROL_MAP: Partial<Record<SBType["name"], InputType["control"]>> = {
- boolean: { type: "boolean" },
- string: { type: "text" },
- number: { type: "number" },
-};
-
-const getManagedParent = (inputType?: StrictInputType) => {
- if (!inputType?.type || inputType.table?.defaultValue?.summary !== "MANAGED_SYMBOL") {
- return undefined;
- }
-
- return walkTree(inputType.type, (elem, parent) =>
- elem.name === "symbol" || (elem.name === "other" && elem.value === "unique symbol")
- ? parent
- : undefined,
- );
-};
-
-export const enhanceManagedSymbol: ArgTypesEnhancer = (context) => {
- Object.values(context.argTypes)
- .map((argType) => {
- const parent = getManagedParent(argType);
- return { argType, parent };
- })
- .filter(({ parent }) => parent)
- .forEach(({ argType, parent }) => {
- const firstAvailableControl = walkTree(
- parent || argType.type!,
- (sb) => SB_TYPE_CONTROL_MAP[sb.name],
- );
-
- if (firstAvailableControl && argType.table?.defaultValue) {
- argType.control = firstAvailableControl;
- argType.table.defaultValue.detail =
- "If no value (or `undefined`) is passed, `MANAGED_SYMBOL` is the internal default value for this prop.\n" +
- "It signals the component that the prop is managed and it's state tracked internally.\n" +
- "So in that case no prop binding or `v-model` is necessary.\n" +
- "Updates for the prop will still be emitted.\n";
- }
- });
-
- return context.argTypes;
-};
+import { createSymbolArgTypeEnhancer } from "@sit-onyx/storybook-utils";
+
+export const enhanceManagedSymbol = createSymbolArgTypeEnhancer(
+ "MANAGED_SYMBOL",
+ "If no value (or `undefined`) is passed, `MANAGED_SYMBOL` is the internal default value for this prop.\n" +
+ "It signals the component that the prop is managed and it's state tracked internally.\n" +
+ "So in that case no prop binding or `v-model` is necessary.\n" +
+ "Updates for the prop will still be emitted.\n",
+);

packages/sit-onyx/.storybook/preview.ts

@@ -9,11 +9,12 @@ import "@fontsource-variable/source-sans-3";
 import "@sit-onyx/storybook-utils/style.css";
 import "../src/styles/index.scss";
 import "./docs-template.scss";
+import { enhanceFormInjectedSymbol } from "./formInjected";
 import { enhanceManagedSymbol } from "./managed";
 import { withOnyxVModelDecorator } from "./vModel";
 
 const basePreview = createPreview({
- argTypesEnhancers: [enhanceManagedSymbol],
+ argTypesEnhancers: [enhanceManagedSymbol, enhanceFormInjectedSymbol],
  parameters: {
  docs: {
  page: docsTemplate,

packages/sit-onyx/src/components/OnyxButton/OnyxButton.vue

@@ -1,14 +1,15 @@
 <script lang="ts" setup>
 import { computed, ref, type ComponentInstance } from "vue";
 import { useDensity } from "../../composables/density";
+import { FORM_INJECTED_SYMBOL, useFormContext } from "../OnyxForm/OnyxForm.core";
 import OnyxIcon from "../OnyxIcon/OnyxIcon.vue";
 import OnyxLoadingIndicator from "../OnyxLoadingIndicator/OnyxLoadingIndicator.vue";
 import OnyxRipple from "../OnyxRipple/OnyxRipple.vue";
 import OnyxSkeleton from "../OnyxSkeleton/OnyxSkeleton.vue";
 import type { OnyxButtonProps } from "./types";
 
 const props = withDefaults(defineProps<OnyxButtonProps>(), {
- disabled: false,
+ disabled: FORM_INJECTED_SYMBOL,
  loading: false,
  type: "button",
  color: "primary",
@@ -17,6 +18,7 @@ const props = withDefaults(defineProps<OnyxButtonProps>(), {
 });
 
 const { densityClass } = useDensity(props);
+const { disabled } = useFormContext(props);
 
 const rippleRef = ref<ComponentInstance<typeof OnyxRipple>>();
 const rippleEvents = computed(() => rippleRef.value?.events ?? {});
@@ -33,7 +35,7 @@ const rippleEvents = computed(() => rippleRef.value?.events ?? {});
  { 'onyx-button--loading': props.loading },
  densityClass,
  ]"
- :disabled="props.disabled || props.loading"
+ :disabled="disabled || props.loading"
  :type="props.type"
  :aria-label="props.loading ? props.label : undefined"
  :autofocus="props.autofocus"

packages/sit-onyx/src/components/OnyxButton/types.ts

@@ -1,5 +1,6 @@
 import type { DensityProp } from "../../composables/density";
 import type { AutofocusProp } from "../../types";
+import type { FormInjected } from "../OnyxForm/OnyxForm.core";
 
 export type OnyxButtonProps = DensityProp &
  AutofocusProp & {
@@ -10,7 +11,7 @@ export type OnyxButtonProps = DensityProp &
  /**
  * If the button should be disabled or not.
  */
- disabled?: boolean;
+ disabled?: FormInjected<boolean>;
  /**
  * Shows a loading indicator.
  */

packages/sit-onyx/src/components/OnyxCheckbox/OnyxCheckbox.vue

@@ -5,14 +5,15 @@ import { useRequired } from "../../composables/required";
 import { useCustomValidity } from "../../composables/useCustomValidity";
 import type { SelectOptionValue } from "../../types";
 import OnyxErrorTooltip from "../OnyxErrorTooltip/OnyxErrorTooltip.vue";
+import { FORM_INJECTED_SYMBOL, useFormContext } from "../OnyxForm/OnyxForm.core";
 import OnyxLoadingIndicator from "../OnyxLoadingIndicator/OnyxLoadingIndicator.vue";
 import OnyxSkeleton from "../OnyxSkeleton/OnyxSkeleton.vue";
 import type { OnyxCheckboxProps } from "./types";
 
 const props = withDefaults(defineProps<OnyxCheckboxProps<TValue>>(), {
  modelValue: false,
  indeterminate: false,
- disabled: false,
+ disabled: FORM_INJECTED_SYMBOL,
  loading: false,
  required: false,
  skeleton: false,
@@ -37,6 +38,7 @@ const { requiredMarkerClass, requiredTypeClass } = useRequired(props);
 const { densityClass } = useDensity(props);
 
 const { vCustomValidity, errorMessages } = useCustomValidity({ props, emit });
+const { disabled } = useFormContext(props);
 
 const title = computed(() => {
  return props.hideLabel ? props.label : undefined;
@@ -49,7 +51,7 @@ const title = computed(() => {
  <OnyxSkeleton v-if="!props.hideLabel" class="onyx-checkbox-skeleton__label" />
  </div>
 
- <OnyxErrorTooltip v-else :disabled="props.disabled" :error-messages="errorMessages">
+ <OnyxErrorTooltip v-else :disabled="disabled" :error-messages="errorMessages">
  <label class="onyx-checkbox" :class="[requiredTypeClass, densityClass]" :title="title">
  <div class="onyx-checkbox__container">
  <OnyxLoadingIndicator v-if="props.loading" class="onyx-checkbox__loading" type="circle" />
@@ -61,7 +63,7 @@ const title = computed(() => {
  class="onyx-checkbox__input"
  type="checkbox"
  :indeterminate="props.indeterminate"
- :disabled="props.disabled"
+ :disabled="disabled"
  :required="props.required"
  :value="props.value"
  :autofocus="props.autofocus"

packages/sit-onyx/src/components/OnyxCheckboxGroup/OnyxCheckboxGroup.vue

@@ -5,14 +5,15 @@ import { useDensity } from "../../composables/density";
 import { injectI18n } from "../../i18n";
 import type { SelectOptionValue } from "../../types";
 import OnyxCheckbox from "../OnyxCheckbox/OnyxCheckbox.vue";
+import { FORM_INJECTED_SYMBOL, useFormContext } from "../OnyxForm/OnyxForm.core";
 import OnyxHeadline from "../OnyxHeadline/OnyxHeadline.vue";
 import type { OnyxCheckboxGroupProps } from "./types";
 
 const props = withDefaults(defineProps<OnyxCheckboxGroupProps<TValue>>(), {
  modelValue: () => [],
  direction: "vertical",
  withCheckAll: false,
- disabled: false,
+ disabled: FORM_INJECTED_SYMBOL,
  truncation: "ellipsis",
 });
 
@@ -38,6 +39,8 @@ const enabledOptionValues = computed(() =>
  props.options.filter((i) => !i.disabled && !i.skeleton).map(({ value }) => value),
 );
 
+const { disabled } = useFormContext(props);
+
 const checkAll = useCheckAll(
  enabledOptionValues,
  computed(() => props.modelValue),
@@ -54,7 +57,7 @@ const checkAllLabel = computed(() => {
 <template>
  <fieldset
  :class="['onyx-checkbox-group', densityClass]"
- :disabled="props.disabled"
+ :disabled="disabled"
  :aria-label="props.label"
  >
  <legend v-if="!props.hideLabel" class="onyx-checkbox-group__label">

packages/sit-onyx/src/components/OnyxCheckboxGroup/types.ts

@@ -2,6 +2,7 @@ import type { DensityProp } from "../../composables/density";
 import type { RequiredMarkerProp } from "../../composables/required";
 import type { CustomValidityProp } from "../../composables/useCustomValidity";
 import type { AutofocusProp, BaseSelectOption, Direction, SelectOptionValue } from "../../types";
+import type { FormInjected } from "../OnyxForm/OnyxForm.core";
 import type { OnyxFormElementProps } from "../OnyxFormElement/types";
 
 export type OnyxCheckboxGroupProps<TValue extends SelectOptionValue = SelectOptionValue> =
@@ -36,7 +37,7 @@ export type OnyxCheckboxGroupProps<TValue extends SelectOptionValue = SelectOpti
  /**
  * Whether all checkboxes should be disabled.
  */
- disabled?: boolean;
+ disabled?: FormInjected<boolean>;
  /**
  * If set, the specified number of skeleton radio buttons will be shown.
  */

packages/sit-onyx/src/components/OnyxForm/OnyxForm.core.spec.ts

@@ -0,0 +1,95 @@
+import { expect, it, vi } from "vitest";
+import { reactive, toValue } from "vue";
+import {
+ FORM_INJECTED_SYMBOL,
+ provideFormContext,
+ useFormContext,
+ type FORM_INJECTED,
+ type FormInjected,
+ type FormInjectedProps,
+} from "./OnyxForm.core";
+
+let injected: (args: unknown[]) => void;
+
+vi.mock("vue", async (importOriginal) => {
+ const mod = await importOriginal<typeof import("vue")>();
+ return {
+ ...mod,
+ inject: () => injected,
+ provide: (_: symbol, ctx: (...args: unknown[]) => void) => (injected = ctx),
+ };
+});
+
+it.for([
+ {
+ formProps: { disabled: true },
+ localProps: { disabled: true },
+ expected: { disabled: true },
+ },
+ {
+ formProps: { disabled: false },
+ localProps: { disabled: true },
+ expected: { disabled: true },
+ },
+ {
+ formProps: { disabled: true },
+ localProps: { disabled: false },
+ expected: { disabled: false },
+ },
+ {
+ formProps: { disabled: false },
+ localProps: { disabled: false },
+ expected: { disabled: false },
+ },
+ {
+ formProps: { disabled: true },
+ localProps: { disabled: FORM_INJECTED_SYMBOL as FORM_INJECTED },
+ expected: { disabled: true },
+ },
+ {
+ formProps: { disabled: false },
+ localProps: { disabled: FORM_INJECTED_SYMBOL as FORM_INJECTED },
+ expected: { disabled: false },
+ },
+ {
+ formProps: undefined,
+ localProps: { disabled: FORM_INJECTED_SYMBOL as FORM_INJECTED },
+ expected: { disabled: false },
+ },
+ {
+ formProps: undefined,
+ localProps: { disabled: true },
+ expected: { disabled: true },
+ },
+ {
+ formProps: undefined,
+ localProps: { disabled: false },
+ expected: { disabled: false },
+ },
+])("it should derive expected state when correctly", ({ formProps, localProps, expected }) => {
+ provideFormContext(formProps);
+ const result = useFormContext(localProps);
+ Object.entries(expected).forEach(([key, value]) => {
+ const resultValue = toValue(result[key as keyof FormInjectedProps]);
+
+ expect(
+ resultValue,
+ `Expected "${value}", got "${resultValue}" for formProps "${formProps}" and localProps "${localProps}"`,
+ ).toBe(value);
+ });
+});
+
+it("should update when changed", async () => {
+ const formProps = reactive({ disabled: false });
+ provideFormContext(formProps);
+
+ const localProps = reactive({ disabled: FORM_INJECTED_SYMBOL as FormInjected<boolean> });
+ const { disabled } = useFormContext(localProps);
+ expect(disabled.value).toBe(false);
+
+ formProps.disabled = true;
+ localProps.disabled = true;
+ expect(disabled.value).toBe(true);
+ localProps.disabled = false;
+ expect(disabled.value).toBe(false);
+});