tide-design-system 2.3.1 → 2.4.1

package/src/docs/forms.md

@@ -0,0 +1,484 @@
+# Tide Input Components Usage Guide
+
+This guide shows how to use `<TideInputText />`, `<TideInputTextarea />`, `<TideInputSelect />` and `<TideInputCheckbox />` in forms, and how to leverage the TIDE library's validation features.
+
+---
+
+## Key Concepts
+
+- `v-model` is used to bind the value to your reactive form state.
+- To react to value changes, parent components can watch for reactive changes to the input's value ref, or use a callback function on the `@update:modelValue` emit.
+- Validation helper props like `required`, `minlength`, `maxlength`, can be used for common validations.
+- Custom validations can be performed using `validators` prop.
+- `error` prop can force a custom validation error with highest precedence.
+- `@valid` event emits every time the input’s validation state changes, allowing reactive updates in real time.
+- Use the `<TideForm />` component for a reliable form submit behavior.
+
+## Input State Management
+
+All TIDE input components use Vue’s built-in [`v-model`](https://vuejs.org/guide/components/v-model) feature to provide **two-way data binding** between your component state and the input’s value.
+
+``` vue
+<script lang="ts" setup>
+import { TideInputText } from 'tide-design-system';
+
+const nameValue = ref<string>(''); // text inputs use a string ref 
+</script>
+
+<template>
+  <TideInputText
+    label="Name"
+    v-model="nameValue"
+  />
+</template>
+```
+
+### What Is “Two-Way Binding” (`v-model`)?
+
+Two-way binding means that data stays in sync **in both directions** between your component’s state and the UI.
+
+#### 1. Upward Binding (User → State)
+
+When a user types into the input, the bound `ref` (`nameValue` in this case) is automatically updated to reflect the new value.
+
+#### 2. Downward Binding (State → UI)
+
+If you modify the `ref` value in your code, the input’s display will automatically update to match.
+
+For example:
+
+```vue
+<TideButton
+  @click="nameValue = nameValue + 'A'"
+  label="Append letter 'A'"
+/>
+```
+
+Clicking this button appends an `"A"` to the existing value of `nameValue`, and you’ll immediately see that change appear in the input field.
+
+For more on `v-model` and two-way data bindings, [see the Vue docs](https://vuejs.org/guide/components/v-model).
+
+### Using `reactive()` for Multiple Inputs
+
+When you have several related input values — such as a form with multiple fields — Vue’s [`reactive()`](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#reactive-objects) helper can make managing state easier. It lets you store all inputs in a single reactive object instead of multiple separate refs.
+
+```vue
+<script lang="ts" setup>
+import { TideInputText, TideButton } from 'tide-design-system'
+
+type FormState = {
+  fullName: string;
+  subscribed: boolean;
+};
+
+const form = reactive<FormState>({
+  fullName: '',
+  subscribed: false,
+});
+</script>
+
+<template>
+  <TideInputText v-model="form.fullName" label="First name" />
+  <TideInputCheckbox v-model="form.subscribed" label="Subscribed" />
+
+  <TideButton
+    @click="form.fullName = form.fullName.toUpperCase()"
+    label="Capitalize name"
+  />
+
+  <pre>{{ form }}</pre>
+</template>
+```
+
+Here’s what’s happening:
+- `form` is a single reactive object holding multiple fields.
+- Each input uses `v-model` to bind directly to a property of `form`.
+- Any change (user or programmatic) to one of the fields is immediately reflected everywhere it’s used — including other components or template bindings like `{{ form }}`.
+
+This approach can help keep your forms organized, especially as the number of inputs grows. [Read more about `reactive()`](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#reactive).
+
+### Reacting to value changes
+
+The recommended way to do something in response to an input's value change is using [Vue watchers](https://vuejs.org/guide/essentials/watchers).
+
+Basic usage:
+
+``` vue
+<script lang="ts" setup>
+const name = ref<string>('');
+
+watch(name, () => {
+  console.log('Name is ' + name.value);
+}, { immediate: true });
+</script>
+
+<template>
+  <TideInputText v-model="name" label="name" />
+</template>
+```
+
+This code will automatically log to the console every time `name` changes. It will also log to the console on mount. [Read about Eager Watchers](https://vuejs.org/guide/essentials/watchers#eager-watchers) (`immediate: true`).
+
+`watchEffect()` is very similar to `watch()`, and can also be used for the same purpose. [Read about `watchEffect()`](https://vuejs.org/guide/essentials/watchers#watcheffect).
+
+**Tip:** You can also conveniently react to value changes with the `@update:modelValue` emit. This is the exact same emit Vue uses under the hood in `v-model`, and it's entirely reliable to hook into to perform a given action every time the value changes. While it's possible to accomplish the same thing using Vue watchers, in some cases simple emits are more ergonomic. [Read more about `v-model` "Under the Hood"](https://vuejs.org/guide/components/v-model#under-the-hood).
+
+
+## Validation
+
+Input components ship with a handful of convenient props for the most common validation use cases. Each component emits the result of its validations as a boolean `@valid`. This emit can be used to reactively apply conditional logic in your parent component in response to validation state changes.
+
+| Prop name | Type | Component | Description |
+| --- | --- | --- | --- |
+| `required` | `boolean` (optional) | All components | Requires the input must not be left blank, or unselected (`TideInputCheckbox`).<br><br> Default: `false` |
+| `minlength` | `number` (optional) | `TideInputText`<br> `TideInputTextarea`<br> | The minimum number of characters required in the input.<br><br> Default: `undefined` |
+| `maxlength` | `number` (optional) | `TideInputText`<br> `TideInputTextarea`<br> | The maximum number of characters allowed in the input.<br><br> Default: `undefined` |
+| `validators` | `Validator[]` (optional) | `TideInputText`<br> `TideInputTextarea`<br>`TideInputSelect`<br> | Provide one or more custom validator functions to run additional validation logic.<br><br> See [Custom Validators](#custom-validators).<br><br> Default: `[]` |
+| `error` | `string` (optional) | All components | Manually specify an error message to display. This prop has the highest precedence of all validations. When provided a non-empty string, it immediately triggers a validation error and prevents other validation rules from running (only one error can be active at a time). When error is an empty string (`''`) or omitted, the component continues normal validation flow (`validators`, `required`, etc.). <br><br> See [Manual Error Messages](#manual-error-messages). <br><br> Default: `''` |
+
+### Validation Precedence
+
+Validations are performed one at a time, and validation is cancelled as soon as an error occurs.
+
+From highest to lowest, the order of precedence for validation is:
+
+1. `error`
+2. `validators`
+3. `required`
+4. `maxlength`
+4. `minlength`
+
+**Note:** Only one error can be active at a time.
+
+### Custom Validators
+
+The `validators` prop accepts one or more custom validator functions to run additional validation logic. Validators can be any function which conforms to `type Validator`.
+
+``` ts
+type ValidationResult = {
+  message: string;
+  valid: boolean;
+};
+type Validator = (value: string) => ValidationResult;
+```
+
+An example of a custom validator could be:
+
+``` vue
+<script lang="ts" setup>
+import { TideInputText } from 'tide-design-system';
+import type { Validator, ValidationResult } from 'tide-design-system';
+
+const nameIsJohnDoe: Validator = (name: string): ValidationResult => {
+  const isValid = name === 'John Doe';
+
+  return {
+    valid: isValid,
+    message: isValid ? '' : 'Name must be "John Doe".',
+  };
+};
+</script>
+
+<template>
+  <!-- Error will show when "Jane Smith" is inputted -->
+  <TideInputText label="Full name" :validators="[nameIsJohnDoe]" />
+</template>
+```
+
+The `tide-design-system` npm package also exposes a `VALIDATOR` const object containing [validator functions for common use cases](https://github.com/traderinteractive/tide-design-system/blob/main/src/types/Validation.ts#:~:text=export%20const%20VALIDATOR%20%3D%20%7B,as%20const%3B).
+
+### Displaying errors
+
+For finer control over when invalid inputs should display errors, each input components accepts an `errorDisplay` prop.
+
+``` ts
+import { ERROR_DISPLAY } from 'tide-design-system';
+```
+
+| `errorDisplay` prop value | Description |
+| --- | --- |
+| `ERROR_DISPLAY.EAGER` | Errors can show after first input focus event. |
+| `ERROR_DISPLAY.LAZY` (default) | Errors can show after first blur event.  |
+
+Unlike the default setting of `ERROR_DISPLAY.LAZY`, the following input would show its error from the `required` prop as soon as it's focused.
+
+``` vue
+<TideInputText
+  :error-display="ERROR_DISPLAY.EAGER"
+  label="Name"
+  required
+  v-model="name"
+/>
+```
+
+### When does validation occur?
+
+Validation is triggered on mount, as well as whenever the following values change:
+- The input's value (`v-model`)
+- `required` prop
+- `minlength`/`maxlength` prop
+- `validators` prop
+- `transform-value` prop
+- `error` prop
+
+So you can trust the `@valid` emit will always provide the most accurate & up to date validation status. But although validation is constantly performed, an input's errors may be visually suppressed if the user hasn't yet interacted with it.
+
+### Forced error reveal on submit
+
+To provide a good form UX, the `<TideForm />` component should be utilized, as when its `@submit` event fires, it automatically reveals any suppressed validation errors on any official TIDE input component descendants. This is particularly useful for cases where a user tries to submit a form before interacting with all required fields. [More on this under `<TideForm />`](#form-submission).
+
+### Accessing Error Messages
+
+`@valid` does not indicate *which* of the validations are valid/invalid. If you need fine-grained control over the validations, it's recommended to *opt out* of all internal validation helper props (`required`, `minlength`, `validators`, etc), and perform your validation manually. You can pass in a custom error message using the `:error` prop.
+
+### Manual error messages
+
+Some use cases require more advanced validation. In such cases it's recommended to opt out of all validation helpers (`minlength`, `maxlength`, `required`, `validators`), and instead use the `:error` prop, paired with your own custom logic. This allows for fine-grained control over your validation, as well as the ability to precisely decide when errors show.
+
+In the following example, we conditionally render a list of ✅ or ❌ icons in real time based on computed validation refs which reactively validate the input's value. `isPasswordValid` checks overall form validity and conditionally applies an `:error` prop to the input, and also prevents execution of `handleSubmit()` until the form is valid.
+
+``` vue
+<script lang="ts" setup>
+import { TideForm, TideInputText, TideButton } from 'tide-design-system';
+
+const password = ref<string>('');
+
+const hasMinLength = computed<boolean>(() => password.value.length >= 12);
+const hasUppercase = computed<boolean>(() => /[A-Z]/.test(password.value));
+const hasLowercase = computed<boolean>(() => /[a-z]/.test(password.value));
+const hasSpecialChar = computed<boolean>(() => /[!@#$%^&*(),.?":{}|<>]/.test(password.value));
+const isPasswordValid = computed<boolean>(() =>
+  hasMinLength.value &&
+  hasUppercase.value &&
+  hasLowercase.value &&
+  hasSpecialChar.value,
+);
+
+const passwordError = computed<string>(() =>
+  (password.value.length > 0 && !isPasswordValid.value)
+    ? 'Password does not meet all requirements.'
+    : '',
+);
+
+const handleSubmit = () => {
+  if (!isPasswordValid.value) return;
+  // ... is valid, register user
+};
+</script>
+
+<template>
+  <TideForm @submit="handleSubmit">
+    <TideInputText
+      label="New password"
+      :type="TEXT_INPUT_TYPE.PASSWORD"
+      v-model="password"
+      :error="passwordError"
+    />
+
+    <ul>
+      <li>{{ hasMinLength ? '✅' : '❌' }} At least 12 characters</li>
+      <li>{{ hasUppercase ? '✅' : '❌' }} An uppercase letter</li>
+      <li>{{ hasLowercase ? '✅' : '❌' }} A lowercase letter</li>
+      <li>{{ hasSpecialChar ? '✅' : '❌' }} A special character</li>
+    </ul>
+
+    <TideButton
+      label="Register"
+      type="submit"
+    />
+  </TideForm>
+</template>
+```
+
+## Form Submission
+
+The `<TideForm />` component provides developers with consistent form submissions. It renders an unstyled `<form />` element, but adds a few subtle enhancements which make forms consistent and improve UX.
+
+### Basic usage:
+
+``` vue
+<script lang="ts" setup>
+import { TideButton, TideForm } from 'tide-design-system';
+
+const handleSubmit = () => {/* ...submit */};
+</script>
+
+<template>
+  <TideForm @submit="handleSubmit">
+    <!-- ...TIDE input components go here -->
+
+    <TideButton
+      label="Submit"
+      type="submit"
+    />
+  </TideForm>
+</template>
+```
+
+### How to Use `<TideForm />`
+
+- Wrap your inputs in a `<TideForm />` component.
+- Attach a submit handler to `@submit` for your custom form logic.
+- Add a submit button (`type="submit"`) inside the form.
+
+**Tip:** It's possible to trigger a form from *anywhere* in the DOM by applying a `form` attribute to a button. The attribute's value must match the unique HTML `id` of the target form element. [Read more about `[form]` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/form).
+
+### Benefits of using `<TideForm />` over `<form />`
+
+With `<TideForm />` you get the following enhancements for free:
+
+#### event.preventDefault()
+`<TideForm />` automatically prevents the browser's native form submit action. This is helpful as we typically want to submit forms using JS — not the native behavior which submits to the server, causing a full page reload. `preventDefault()` causes this native behavior to be ignored, yet the `@submit` event still fires, giving you full control over what happens when the user triggers form submission.
+
+[Read about `preventDefault()` on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault).
+
+#### novalidate
+
+When a submit request is fired, the browser looks for various native validation-related attributes like [`[maxlength]`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/maxlength), [`[required]`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/required) or [`[pattern]`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/pattern), and checks that the input's values are valid. If any values are invalid, it will prevent the submit event from firing, and it will show some error messages like so:
+
+<p>
+  <img src="./assets/native-input-validation.png" width="360" />
+</p>
+
+But our components have their own Vue-based validation mechanisms, so we want to bypass this native behavior. `[novalidate]` being placed on the form element opts out of this native behavior.
+
+[Read about `novalidate` on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/noValidate).
+
+#### Show errors on submit
+
+Sometimes a user will attempt to submit a form before they've interacted with all required inputs. In this case it's crucial that the user is made aware they need to adjust some form values. For this reason, when a `<TideForm />` is submitted, it will cause any suppressed errors to be made visible, preventing potential user frustration.
+
+---
+
+## Minimal Reactive Single-Input Example
+
+This is a simple example of a text input connected to a local `Ref<string>`. A `Ref<boolean>` separately tracks the validation state via the `@valid` emit, whose validation status is stored, and referenced when the user tries to submit. If the keyword input is invalid we cancel the submission as they need to modify their input.
+
+```vue
+<script lang="ts" setup>
+import { TideButton, TideForm, TideInputText } from 'tide-design-system';
+
+const keyword = ref<string>('');
+const isKeywordValid = ref<boolean>(false);
+
+const handleSubmit = () => {
+  if (!isKeywordValid.value) return;
+  // ...perform search
+};
+</script>
+
+<template>
+  <TideForm @submit="handleSubmit">
+    <TideInputText
+      label="Keyword"
+      required
+      v-model="keyword"
+      @valid="isKeywordValid = $event"
+    />
+
+    <TideButton
+      label="Search"
+      type="submit"
+    />
+  </TideForm>
+</template>
+```
+
+---
+
+### Multi-Input Reactive Form Example
+
+This more complex example contains a mix of input types. It also uses a mix of many kinds of validations.
+
+A `reactive({})` ref is used here to conveniently store all form values together. A second `reactive({})` tracks the validation as a boolean for each input. A computed ref checks whether validation passes for all fields. Once again, this value is checked in the submit event handler to cancel submission if the form has errors. As [mentioned earlier](#show-errors-on-submit), form submits will automatically reveal any suppressed errors, which helps users know what they must do next.
+
+```vue
+<script lang="ts" setup>
+  import {
+    TideButton,
+    TideForm,
+    TideInputCheckbox,
+    TideInputSelect,
+    TideInputText,
+    TideInputTextarea,
+    VALIDATOR,
+  } from 'tide-design-system';
+
+  const form = reactive({
+    bio: '',
+    country: '',
+    fullName: '',
+    terms: false,
+  });
+
+  const validation = reactive({
+    bio: false,
+    country: false,
+    fullName: false,
+    terms: false,
+  });
+
+  const isFormValid = computed<boolean>(() => [
+    validation.bio,
+    validation.country,
+    validation.fullName,
+    validation.terms,
+  ].every(Boolean));
+
+  const handleSubmit = () => {
+    if (!isFormValid.value) return;
+    // ...register user
+  };
+</script>
+
+<template>
+  <TideForm @submit="handleSubmit">
+    <TideInputText
+      :maxlength="24"
+      :validators="[VALIDATOR.ALPHA_SPACE]"
+      @valid="validation.fullName = $event"
+      label="Full name"
+      required
+      v-model="form.fullName"
+    />
+
+    <TideInputTextarea
+      :maxlength="500"
+      @valid="validation.bio = $event"
+      label="Bio"
+      v-model="form.bio"
+    />
+
+    <TideInputSelect
+      :options="[
+        { label: 'US', value: 'us' },
+        { label: 'Canada', value: 'ca' },
+      ]"
+      @valid="validation.country = $event"
+      label="Country"
+      required
+      v-model="form.country"
+    />
+
+    <TideInputCheckbox
+      @valid="validation.terms = $event"
+      label="Accept terms & conditions"
+      required
+      v-model="form.terms"
+    />
+
+    <TideButton
+      label="Register"
+      type="submit"
+    />
+  </TideForm>
+</template>
+```
+
+## Further reading
+
+Instead of disabling form submit buttons, consider leaving them enabled, but provide the user with visual feedback indicating the form is not yet submittable. Don't forget that just because an HTML form's submit button is disabled doesn't mean it can't be submittable. The `Enter`/`Return` key, or other mechanisms can still trigger the `@submit` event.
+
+Read more:
+- [The problem with disabled buttons and what to do instead](https://adamsilver.io/blog/the-problem-with-disabled-buttons-and-what-to-do-instead/) - Adam Silver
+- [Don’t Disable Form Controls](https://adrianroselli.com/2024/02/dont-disable-form-controls.html) - Adrian Roselli

package/src/docs/upgrading.md

@@ -4,9 +4,52 @@ This document provides step-by-step instructions for upgrading from previous ver
 
 ---
 
+## Upgrading from 2.3 → 2.4
+
+### Summary
+Version **2.4** introduces a new suite of form components. It remains largely backward-compatible with the previous versions of components, but requires an update to a number of component names. It also removes a number of form-related TS exports.
+
+### Migration steps
+
+1. **Convert component names**
+
+These components have been changed, and must be renamed as follows:
+
+| Old name (2.3) | New name (2.4) |
+|---|---|
+| `<TideInputCheckbox />` | `<TideInputCheckboxDeprecated />` |
+| `<TideInputRadio />` | `<TideInputRadioDeprecated />` |
+| `<TideInputSelect />` | `<TideInputSelectDeprecated />` |
+| `<TideInputText />` | `<TideInputTextDeprecated />` |
+| `<TideInputTextarea />` | `<TideInputTextareaDeprecated />` |
+
+The components are otherwise identical.
+
+2. **Replace usage of removed types**
+
+The following types are no longer exported from the TIDE repository and must be replaced:
+- `BooleanInput`
+- `BooleanValue`
+- `CheckboxField`
+- `CheckboxInput`
+- `Field`
+- `GenericField`
+- `GenericInput`
+- `Input`
+- `SelectField`
+- `SelectInput`
+- `StringField`
+- `StringInput`
+- `StringValue`
+- `TextField`
+- `TextareaField`
+- `TextareaInput`
+
+✅ After these changes your project should be compatible with **TIDE 2.4**.
+
 ## Upgrading from 2.2 → 2.3
 
-**Summary**  
+### Summary
 Version **2.3** consolidates certain CSS files. The same utilities can now be made globally available in a TIDE consumer repository leveraging [partial integration](./integration-partial.md) by cherry-picking a smaller set of `dist` files from the `node_modules` subdirectory.
 
 **Important:** Upgrading to **2.3** introduces breaking changes unless deprecated imports are removed.

package/src/stories/FoundationsBorder.stories.ts

@@ -1,8 +1,10 @@
 import * as STYLES from '@/types/Storybook';
-import { formatArgType, getConstantsByValues, prependNoneAsEmpty } from '@/utilities/storybook';
+import { CSS } from '@/types/Styles';
+import { flatten, formatArgType, getConstantsByValues, prependNoneAsEmpty } from '@/utilities/storybook';
 
 import type { StoryContext } from '@storybook/vue3';
 
+const BORDER_COLOR = prependNoneAsEmpty(flatten(CSS.BORDER.COLOR));
 const BORDER_RADIUS = prependNoneAsEmpty(STYLES.BORDER_RADIUS);
 const BORDER_SIDE = prependNoneAsEmpty(STYLES.BORDER_SIDE);
 const BORDER_STYLE = prependNoneAsEmpty(STYLES.BORDER_STYLE);
@@ -16,18 +18,21 @@ const formatArgs = (args: any) => {
 
 const formatClassNames = (args: any) => {
   const classNames: string[] = [];
+  const hasBorder = args.borderSide || args.borderWidth;
 
-  if (args.borderSide === BORDER_SIDE.Full && args.borderWidth && args.borderRadius) {
-    classNames.push(args.borderRadius);
-  }
+  // Any selection for any property should also add a side and width or nothing will be visible.
+  if (hasBorder) {
+    const side = args.borderSide || BORDER_SIDE.Full;
+    const width = args.borderWidth || BORDER_WIDTH['1px'];
 
-  if (args.borderSide && args.borderWidth) {
-    classNames.push(`${args.borderSide}-${args.borderWidth}`);
+    classNames.push(`${side}-${width}`);
+  } else if (args.borderStyle || args.borderColor || args.borderRadius) {
+    classNames.push(CSS.BORDER.FULL.ONE);
   }
 
-  if (args.borderSide && args.borderWidth && args.borderStyle) {
-    classNames.push(args.borderStyle);
-  }
+  if (args.borderStyle) classNames.push(args.borderStyle);
+  if (args.borderColor) classNames.push(args.borderColor);
+  if (args.borderRadius) classNames.push(args.borderRadius);
 
   return classNames;
 };
@@ -67,22 +72,28 @@ const render = (args: any) => ({
 
 export default {
   argTypes: {
+    borderColor: {
+      ...formatArgType({ BORDER_COLOR }),
+      description: 'Applies a border color',
+      name: 'Border Color',
+      table: {
+        defaultValue: { summary: 'None' },
+        type: { summary: 'CSS.BORDER.COLOR' },
+      },
+    },
     borderRadius: {
       ...formatArgType({ BORDER_RADIUS }),
       description: 'Dictates severity of rounded corners',
-      if: { arg: 'borderSide', eq: BORDER_SIDE.Full },
       name: 'Border Radius',
     },
     borderSide: {
       ...formatArgType({ BORDER_SIDE }),
       description: 'Dictates to which edge(s) the border applies',
-      if: { arg: 'borderWidth', neq: BORDER_WIDTH.None },
       name: 'Border Side',
     },
     borderStyle: {
       ...formatArgType({ BORDER_STYLE }),
       description: 'Applies a border style',
-      if: { arg: 'borderWidth', neq: BORDER_STYLE.None },
       name: 'Border Style',
     },
     borderWidth: {
@@ -92,6 +103,7 @@ export default {
     },
   },
   args: {
+    borderColor: BORDER_COLOR.None,
     borderRadius: BORDER_RADIUS.None,
     borderSide: BORDER_SIDE.None,
     borderStyle: BORDER_STYLE.None,
@@ -200,7 +212,7 @@ export const BorderFullDashed2px = {
     borderStyle: BORDER_STYLE.Dashed,
     borderWidth: BORDER_WIDTH['2px'],
   },
-  name: 'Border Full Dashed 1px',
+  name: 'Border Full Dashed 2px',
 };
 
 export const RadiusQuarter = {