@iress-oss/ids-mcp-server 5.14.2 → 5.20.1

package/generated/docs/components_components-input-recipes-docs.md

@@ -0,0 +1,367 @@
+Recipes
+=======
+
+Percentage formatting
+---------------------
+
+You can use `IressInput` to display percentage formatting. When the field is focused, it can display the raw value, and when blurred, it can display the formatted percentage value.
+
+[](./iframe.html?id=components-input-recipes--percentage)
+
+```
+
+import { IressInput } from '@iress-oss/ids-components';
+export const InputPercentage \= () \=> (
+  <IressInput<number | string\>
+    defaultValue\="0.5"
+    formatter\={(value \= '') \=> {
+      if (value \=== '') return '';
+      const numericValue \= Number(value);
+      if (Number.isNaN(numericValue)) {
+        return String(value) ?? '';
+      }
+      return new Intl.NumberFormat('en-AU', {
+        style: 'percent',
+      }).format(numericValue);
+    }}
+    type\="number"
+  /\>
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alignRight | 
+Set input content align to right.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Content to append to the input field, usually a button or icon.
+
+ReactReactNode
+
+
+
+ | \- | Set object |
+| clearable | 
+
+If `true`, then user can clear the value of the input. Will be ignored if `rows` prop is in use.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| defaultValue | 
+
+The value of the input. Can be a string or a number. Use for uncontrolled inputs.
+
+T
+
+
+
+ | \- | Set object |
+| formatter | 
+
+Bring your own formatter that will be used to format the value when the input is not focused, allowing you to display the value in a different format. e.g. User type in value="dsf 987kkk123" => result after formatter: $987,123 (string)
+
+(value?: T) => string | number
+
+ | \- | \- |
+| inline | 
+
+Make prepend/append element closer to the input content.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| loading | 
+
+The loading states of the input field. If provided a string, will use that text as the loading message.
+
+union
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the input value changes with the new changed value.
+
+(e: React.ChangeEvent<InputBaseElement>, value: T) => void
+
+ | \- | \- |
+| onClear | 
+
+Emitted when the input is manually cleared.
+
+(e: React.ChangeEvent<InputBaseElement>) => void
+
+ | \- | \- |
+| prepend | 
+
+Content to prepended to the input field, usually an icon.
+
+ReactReactNode
+
+
+
+ | \- | Set object |
+| value | 
+
+The value of the input. Can be a string or a number. Use for controlled inputs.
+
+T
+
+
+
+ | \- | Set object |
+| watermark | 
+
+When set to `true` add ons will render with a different style. Will be ignored if `prepend` or `append` props are not being used.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| width | 
+
+The width of the input.
+
+union
+
+
+
+ | \- | Set object |
+
+Using with React Hook Forms
+---------------------------
+
+You can use `IressInput` with React Hook Forms quite easily. The recommended way is to use the [`Controller` component from react-hook-forms](https://www.react-hook-form.com/get-started/#IntegratingwithUIlibraries). However, you can use the `register` method directly, with a few customisations to cater for custom `ref` as seen in the code example here.
+
+Where possible, please use `IressFormField` within an [`IressForm` component](/docs/components-form--docs).
+
+[](./iframe.html?id=components-input-recipes--react-hook-forms)
+
+Although you can use `IressInput` directly with React Hook Forms, we recommend using `IressFormField` within `IressForm` for a more integrated experience.
+
+Input using `{ Controller } from 'react-hook-forms'`
+
+Input using `{ register } = useForm()`
+
+Submit
+
+```
+
+import {
+  type InputRef,
+  IressAlert,
+  IressButton,
+  IressInline,
+  IressInput,
+  IressLabel,
+  IressModal,
+  IressStack,
+  IressTable,
+} from '@iress-oss/ids-components';
+import { useState } from 'react';
+import {
+  Controller,
+  type UseFormRegisterReturn,
+  useForm,
+} from 'react-hook-form';
+const registerInnerElement \= (register: UseFormRegisterReturn) \=> {
+  return {
+    ...register,
+    onClear: register.onChange,
+    ref: (ref: InputRef | null) \=> {
+      if (ref) {
+        register.ref(ref.input);
+      }
+    },
+  };
+};
+export const ReactHookFormsInput \= () \=> {
+  const { register, handleSubmit, control } \= useForm();
+  const \[data, setData\] \= useState<Record<string, string\> | undefined\>();
+  return (
+    // eslint-disable-next-line sonarjs/void-use -- This is a mock form submission
+    <form onSubmit\={void handleSubmit(setData)}\>
+      <IressStack gutter\="md"\>
+        <IressAlert status\="info"\>
+          Although you can use <code\>IressInput</code\> directly with React Hook          Forms, we recommend using <code\>IressFormField</code\> within{' '}
+          <code\>IressForm</code\> for a more integrated experience.        </IressAlert\>
+        <IressInline gutter\="md" verticalAlign\="middle"\>
+          <IressLabel htmlFor\="Controller"\>
+            Input using <code\>{\`{ Controller } from 'react-hook-forms'\`}</code\>
+          </IressLabel\>
+          <Controller
+            name\="Controller"
+            control\={control}
+            render\={({ field }) \=> (
+              <IressInput
+                {...field}
+                clearable
+                onClear\={field.onChange}
+                id\="firstName"
+              />
+            )}
+          />
+        </IressInline\>
+        <IressInline gutter\="md" verticalAlign\="middle"\>
+          <IressLabel htmlFor\="register"\>
+            Input using <code\>{\`{ register } = useForm()\`}</code\>
+          </IressLabel\>
+          <IressInput
+            {...registerInnerElement(register('register'))}
+            clearable
+            id\="register"
+          />
+        </IressInline\>
+        <IressButton type\="submit"\>Submit</IressButton\>
+      </IressStack\>
+      {data && (
+        <IressModal
+          show\={!!data}
+          onShowChange\={(show) \=> !show && setData(undefined)}
+        \>
+          <IressTable
+            caption\="Submitted details"
+            rows\={Object.entries(data ?? {}).map((entry) \=> ({
+              name: entry\[0\],
+              value: JSON.stringify(entry\[1\], null, 2),
+            }))}
+          />
+        </IressModal\>
+      )}
+    </form\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alignRight | 
+Set input content align to right.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| append | 
+
+Content to append to the input field, usually a button or icon.
+
+ReactReactNode
+
+
+
+ | \- | Set object |
+| clearable | 
+
+If `true`, then user can clear the value of the input. Will be ignored if `rows` prop is in use.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| defaultValue | 
+
+The value of the input. Can be a string or a number. Use for uncontrolled inputs.
+
+T
+
+
+
+ | \- | Set object |
+| formatter | 
+
+Bring your own formatter that will be used to format the value when the input is not focused, allowing you to display the value in a different format. e.g. User type in value="dsf 987kkk123" => result after formatter: $987,123 (string)
+
+(value?: T) => string | number
+
+ | \- | \- |
+| inline | 
+
+Make prepend/append element closer to the input content.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| loading | 
+
+The loading states of the input field. If provided a string, will use that text as the loading message.
+
+union
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the input value changes with the new changed value.
+
+(e: React.ChangeEvent<InputBaseElement>, value: T) => void
+
+ | \- | \- |
+| onClear | 
+
+Emitted when the input is manually cleared.
+
+(e: React.ChangeEvent<InputBaseElement>) => void
+
+ | \- | \- |
+| prepend | 
+
+Content to prepended to the input field, usually an icon.
+
+ReactReactNode
+
+
+
+ | \- | Set object |
+| value | 
+
+The value of the input. Can be a string or a number. Use for controlled inputs.
+
+T
+
+
+
+ | \- | Set object |
+| watermark | 
+
+When set to `true` add ons will render with a different style. Will be ignored if `prepend` or `append` props are not being used.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| width | 
+
+The width of the input.
+
+union
+
+
+
+ | \- | Set object |