@czi-sds/mcp 0.16.0 → 0.18.0

package/data/component-docs/InputSearch.md

@@ -0,0 +1,81 @@
+# InputSearch
+
+## Source Code
+
+The component's source code in the SDS codebase can be found [here](https://github.com/chanzuckerberg/sci-components/blob/main/packages/components/src/core/InputSearch/index.tsx).
+
+## Import
+
+**React TypeScript**
+
+```tsx
+import { InputSearch } from "@czi-sds/components";
+```
+
+## Code examples
+
+### **Default InputSearch**
+
+This example has the minimum props needed for the InputSearch component.
+
+**Example: DefaultInputSearch**
+
+```tsx
+import { InputSearch } from "@czi-sds/components";
+import { Box } from "@mui/material";
+
+function App() {
+  return (
+    <div className="app">
+      <Box sx={{ width: 300 }}>
+        <InputSearch id="search-input" label="search" placeholder="Search" />
+      </Box>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## SDS vs MUI
+
+SDS's InputSearch is built on MUI's TextField component, with `type="search"`. It also has the SDS "search" icon automatically included, aligned to the right end of the field.
+
+The following props are available to MUI's TextField component, but do not work the same way (or at all) for SDS's InputSearch component:
+
+- `variants`: SDS's InputSearch component is not set up to support values for this prop (aside from `"outlined"`, InputSearch default), and using other values available to MUI (`"filled"`, `"standard"`) may result in unreliable outputs
+
+- `size`: SDS's InputSearch component is not set up to support values for this prop (aside from `"small"`, InputText's default), and using other values available to MUI (`"medium"`, `"large"`) may not have reliable outputs
+
+- `required`: SDS's InputSearch does not render the expected asterisk (\*) following the label when this prop is `true`
+
+- `select`: SDS's InputSearch is not set up to support this boolean prop
+
+- `hiddenLabel`: The label (`"Search"`, by default) for SDS's component is included within the search field, not outside of it, and the MUI `hiddenLabel` prop will not hide the label
+
+The following functionality is available to both MUI's TextField component and SDS's InputText component, but SDS uses different prop names, shown below:
+
+- `intent`: This prop is the way you can set colors for SDS's InputText, based on its error state. It takes default (default, gray), error, or warning as values. The related MUI-color-setting prop, `color`, has no effect for InputText in SDS.
+
+SDS's InputSearch has an additional `sdsStyle` prop to help with setting SDS-specific styles, which takes `"square"` (default) or `"rounded"` as values.
+
+## MUI Documentation
+
+Documentation for the underlying MUI TextField component can be found [here](https://mui.com/material-ui/react-text-field/).
+
+## Props
+
+Any custom SDS props and MUI props required for implementation are found on the table below. See the MUI documentation for additional optional props.
+
+| Name           | Type                                                      | Default                                      | Description                                                                                                                           |
+| -------------- | --------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `classes`      | `object`                                                  | `{}`                                         | Class names for the internal elements: `root`, `label`, `input`, `endAdornment`, `startAdornment`, `clearButton`, and `searchButton`. |
+| `disabled`     | `boolean`                                                 | `false`                                      | When set to `true`, the component becomes disabled and cannot be interacted with.                                                     |
+| `handleSubmit` | `function`                                                | `function(value: string) => void`            | This function is called when the Search icon is clicked, allowing user to handle the search operation.                                |
+| `id`           | `string`                                                  | -                                            | Specifies the unique id for the input element, needed for accessibility.                                                              |
+| `intent`       | `"default"` \| `"negative"` \| `"notice"` \| `"positive"` | `"default"`                                  | Alters the border color and visual intent of the search input.                                                                        |
+| `label`        | `string`                                                  | -                                            | Although hidden, this label is provided for accessibility purposes.                                                                   |
+| `onChange`     | `function`                                                | `function(event: React.ChangeEvent) => void` | Defines the action to be taken when the input value changes.                                                                          |
+| `placeholder`  | `string`                                                  | `"Search"`                                   | Sets the placeholder text displayed within the input element.                                                                         |
+| `sdsStyle`     | `"rounded"` \| `"square"`                                 | `"square"`                                   | Determines the visual style of the component, with options for rounded or square design.                                              |
+| `value`        | `string`                                                  | -                                            | The value of the `input` element, required for a controlled component.                                                                |

package/data/component-docs/InputSlider.md

@@ -0,0 +1,189 @@
+# InputSlider
+
+## Source Code
+
+The component's source code in the SDS codebase can be found [here](https://github.com/chanzuckerberg/sci-components/blob/main/packages/components/src/core/InputSlider/index.tsx).
+
+## Import
+
+**React TypeScript**
+
+```tsx
+import { InputSlider } from "@czi-sds/components";
+```
+
+## Code examples
+
+### **Default InputSlider**
+
+This example has the minimum props needed for the InputSlider component.
+
+**Example: DefaultInputSlider**
+
+```tsx
+import { InputSlider } from "@czi-sds/components";
+import { Box } from "@mui/material";
+
+function App() {
+  return (
+    <div className="app">
+      <Box sx={{ width: 200 }}>
+        <InputSlider aria-label="Label" defaultValue={50} />
+      </Box>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### InputSlider with custom Marks
+
+This example shows an InputSlider component that features custom marks precisely positioned at 0%, 50%, and 100% of the slider's value.
+
+**Example: InputSliderWithCustomMarks**
+
+```tsx
+import { InputSlider } from "@czi-sds/components";
+import { Box } from "@mui/material";
+
+const generateCustomMarks = (min: number, max: number) => {
+  return [
+    {
+      label: min,
+      value: min,
+    },
+    {
+      label: ((max - min) / 2 + min).toFixed(0),
+      value: (max - min) / 2 + min,
+    },
+    {
+      label: max,
+      value: max,
+    },
+  ];
+};
+
+function App() {
+  return (
+    <div className="app">
+      <Box sx={{ width: 200 }}>
+        <InputSlider
+          aria-label="Label"
+          defaultValue={50}
+          marks={generateCustomMarks(0, 100)}
+          min={0}
+          max={100}
+          step={5}
+          valueLabelDisplay="on"
+        />
+      </Box>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Range InputSlider
+
+Passing an array of two numbers renders a range with a thumb at each end.
+
+**Example: RangeInputSlider**
+
+```tsx
+// An array value turns the slider into a range with two thumbs, which the
+// component labels "Minimum value" and "Maximum value" for screen readers.
+import { InputSlider } from "@czi-sds/components";
+import { Box } from "@mui/material";
+
+function App() {
+  return (
+    <div className="app">
+      <Box sx={{ width: 200 }}>
+        <InputSlider
+          defaultValue={[15, 85]}
+          min={0}
+          max={100}
+          step={5}
+          valueLabelDisplay="on"
+        />
+      </Box>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Disabled InputSlider
+
+A disabled slider dims the track, thumb, marks, and value label, and ignores pointer and keyboard input.
+
+**Example: DisabledInputSlider**
+
+```tsx
+import { InputSlider } from "@czi-sds/components";
+import { Box } from "@mui/material";
+
+function App() {
+  return (
+    <div className="app">
+      <Box sx={{ width: 200 }}>
+        <InputSlider
+          aria-label="Label"
+          defaultValue={40}
+          marks
+          step={20}
+          valueLabelDisplay="on"
+          disabled
+        />
+      </Box>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## SDS vs MUI
+
+The following props and options differ in how they function across MUI's Slider component versus SDS's InputSlider component:
+
+- `orientation`: Has no effect in SDS. The component always renders horizontally, and overrides anything you pass.
+
+- `size` and `color`: Have no effect in SDS. The rail, track, and thumb are styled from the theme.
+
+- `aria-label` and `getAriaLabel`: SDS labels the thumbs for you. A range slider gets `"Minimum value"` and `"Maximum value"`; a single-thumb slider uses your `aria-label`, falling back to `"Slider value"`. Pass `getAriaLabel` to take over completely.
+
+These are some of the common props that can be used for both the MUI Slider component and the SDS InputSlider component:
+
+- `value` and `defaultValue`: A number renders one thumb. An array of two numbers renders a range with two thumbs, as in the "Range InputSlider" example below.
+
+- `step`: Sets the step distance between selectable stops (and relatedly, if this prop is left out, the slider is continuous, rather than discrete)
+
+- `marks`: When present and set to `true`, invokes the default marks style. When passed a rich array (of objects containing the value and the custom label to show at that value), sets marks and labels only at the positions specified by the array. See the "InputSlider with custom Marks" example below.
+
+- `valueLabelDisplay`: This prop determines whether and when the value label is displayed, and takes the following props: `"auto"` (the value label will display when the thumb is hovered or focused), `"on"` (labels display persistently), or `"off"` (default; labels are never displayed).
+
+## MUI Documentation
+
+Documentation for the underlying MUI component can be found [here](https://mui.com/material-ui/react-slider/).
+
+## Props
+
+Any custom SDS props and MUI props required for implementation are found on the table below. See the MUI documentation for additional optional props.
+
+| Name                | Type                                  | Default          | Description                                                                                                                                                                                                                                                                                                   |
+| ------------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultValue`      | `Array<number> \| number`             | -                | The default value. Use when the component is not controlled. An array of two numbers renders a range slider.                                                                                                                                                                                                  |
+| `value`             | `Array<number> \| number`             | -                | The value of the slider. Use with `onChange` to control the component.                                                                                                                                                                                                                                        |
+| `onChange`          | `(event, value, activeThumb) => void` | -                | Called as the user drags a thumb.                                                                                                                                                                                                                                                                             |
+| `disabled`          | `boolean`                             | `false`          | If `true`, the component is disabled.                                                                                                                                                                                                                                                                         |
+| `marks`             | `bool \| Array<{ value, label }>`     | `false`          | Marks indicate predetermined values to which the user can move the slider. If `true` the marks are spaced according the value of the `step` prop. If an array, it should contain objects with `value` and an optional `label` keys.                                                                           |
+| `max`               | `number`                              | `100`            | The maximum allowed value of the slider. Should not be equal to `min`.                                                                                                                                                                                                                                        |
+| `min`               | `number`                              | `0`              | The minimum allowed value of the slider. Should not be equal to `max`.                                                                                                                                                                                                                                        |
+| `orientation`       | `"horizontal"`                        | `"horizontal"`   | Fixed by SDS. The component sets this itself, so a vertical slider is not available.                                                                                                                                                                                                                          |
+| `step`              | `number`                              | `1`              | The granularity with which the slider can step through values. (A "discrete" slider.) The `min` prop serves as the origin for the valid values. We recommend `(max - min)` to be evenly divisible by the `step`. When `step` is `null`, the thumb can only be slid onto marks provided with the `marks` prop. |
+| `valueLabelDisplay` | `"auto"` \| `"off"` \| `"on"`         | `"off"`          | Controls when the value label is displayed: - `"auto"` the value label will display when the thumb is hovered or focused. - `"on"` will display persistently. - `"off"` will never display.                                                                                                                   |
+| `aria-label`        | `string`                              | `"Slider value"` | Labels the thumb of a single-value slider. Range sliders label their two thumbs `"Minimum value"` and `"Maximum value"` instead.                                                                                                                                                                              |

package/data/component-docs/InputText.md

@@ -0,0 +1,110 @@
+# InputText
+
+## Source Code
+
+The component's source code in the SDS codebase can be found [here](https://github.com/chanzuckerberg/sci-components/blob/main/packages/components/src/core/InputText/index.tsx).
+
+## Import
+
+**React TypeScript**
+
+```tsx
+import { InputText } from "@czi-sds/components";
+```
+
+## Code examples
+
+### **InputText – Text Field**
+
+This component represents the text field variant of the InputText component.
+
+**Example: InputTextTextField**
+
+```tsx
+import { InputText } from "@czi-sds/components";
+import { Box } from "@mui/material";
+
+function App() {
+  return (
+    <div className="app">
+      <Box sx={{ width: 300 }}>
+        <InputText
+          id="search-input"
+          label="Label"
+          placeholder="Enter your text"
+          hideLabel
+        />
+      </Box>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### InputText – Text Area
+
+This component represents the text area variant of the InputText component.
+
+**Example: InputTextTextArea**
+
+```tsx
+import { InputText } from "@czi-sds/components";
+import { Box } from "@mui/material";
+
+function App() {
+  return (
+    <div className="app">
+      <Box sx={{ width: 300 }}>
+        <InputText
+          id="search-input"
+          label="Description"
+          placeholder="Enter your text"
+          sdsType="textArea"
+        />
+      </Box>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## SDS vs MUI
+
+Like SDS's InputSearch (which is also built upon the same MUI component), the following props and options do not work the same way (or at all) for SDS's InputText component even though they are available to MUI's TextField component.
+
+- `variants`: SDS's InputText component is not set up to support values for this prop (aside from `"outlined"`, InputText's default), and using other values available to MUI (`"filled"`, `"standard"`) may result in unreliable outputs
+
+- `size`: SDS's InputText component is not set up to support values for this prop (aside from `"small"`, InputText's default), and using other values available to MUI (`"medium"`, `"large"`) may not have reliable outputs
+
+- `required`: SDS's InputText does not render the expected asterisk (\*) following the label when this prop is `true`
+
+- `select`: SDS's InputText is not set up to support this boolean prop
+
+The following functionality is available to both MUI's TextField component and SDS's InputText component, but SDS uses different prop names, shown below:
+
+- `sdsType`: This is the SDS-equivalent of MUI's boolean `multiline` prop, and takes `"textField"` (default) or `"textArea"` as values
+
+- `hideLabel`: This is the SDS-equivalent of the `hiddenLabel` prop used in MUI; both are boolean with the default not including them (value of `false`)
+
+- `intent`: This prop is the way you can set colors for SDS's InputText, based on its error state. It takes default (default, gray), error, or warning as values. The related MUI-color-setting prop, `color`, has no effect for InputText in SDS.
+
+## MUI Documentation
+
+Documentation for the underlying MUI TextFieldcomponent can be found [here](https://mui.com/material-ui/react-text-field/).
+
+## Props
+
+Any custom SDS props and MUI props required for implementation are found on the table below. See the MUI documentation for additional optional props.
+
+| Name          | Type                                                      | Default       | Description                                                                          |
+| ------------- | --------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ |
+| `classes`     | `object`                                                  | `{}`          | Class names for the internal elements: `root`, `label`, and `input`.                 |
+| `disabled`    | `boolean`                                                 | `false`       | When set to `true`, the component becomes disabled and cannot be interacted with.    |
+| `hideLabel`   | `boolean`                                                 | `false`       | If `true`, the label is hidden.                                                      |
+| `id`          | `string`                                                  | -             | Specifies the unique id for the input element, needed for accessibility.             |
+| `intent`      | `"default"` \| `"negative"` \| `"notice"` \| `"positive"` | `"default"`   | Alters the border color and visual intent of the search input.                       |
+| `label`       | `string`                                                  | -             | The label for the input element.                                                     |
+| `placeholder` | `string`                                                  | -             | Sets the placeholder text displayed within the input element.                        |
+| `sdsType`     | `"textField"` \| `"textArea"`                             | `"textField"` | Defines the type of component to render, with options for a text input or text area. |

package/data/component-docs/InputToggle.md

@@ -0,0 +1,141 @@
+# InputToggle
+
+## Source Code
+
+The component's source code in the SDS codebase can be found [here](https://github.com/chanzuckerberg/sci-components/blob/main/packages/components/src/core/InputToggle/index.tsx).
+
+## Import
+
+**React TypeScript**
+
+```tsx
+import { InputToggle } from "@czi-sds/components";
+```
+
+## Code examples
+
+### **Default InputToggle**
+
+This example has the minimum props needed for the InputToggle component.
+
+**Example: DefaultInputToggle**
+
+```tsx
+import { InputToggle } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app">
+      <InputToggle />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### **InputToggle with customized on and off labels**
+
+This example shows an InputToggle component with customized on and off labels, widened to fit them.
+
+**Example: InputToggleWithCustomizedOnAndOffLabels**
+
+```tsx
+import { InputToggle } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app">
+      <InputToggle onLabel="Start" offLabel="Finish" width={72} />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### **Controlled InputToggle**
+
+Passing `checked` hands control of the toggle to your application, which then updates it from the `onChange` handler.
+
+**Example: ControlledInputToggle**
+
+```tsx
+// Passing `checked` makes the toggle controlled; without it the component
+// tracks its own state.
+import { useState } from "react";
+import { InputToggle } from "@czi-sds/components";
+
+function App() {
+  const [checked, setChecked] = useState(true);
+
+  return (
+    <div
+      className="app"
+      style={{ alignItems: "center", display: "flex", gap: "16px" }}
+    >
+      <InputToggle
+        checked={checked}
+        onChange={() => setChecked((previous) => !previous)}
+      />
+      <span>Notifications are {checked ? "on" : "off"}</span>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### **Disabled InputToggle**
+
+This example shows a disabled InputToggle in both its off and on states.
+
+**Example: DisabledInputToggle**
+
+```tsx
+import { InputToggle } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app" style={{ display: "flex", gap: "16px" }}>
+      <InputToggle disabled />
+      <InputToggle checked disabled />
+    </div>
+  );
+}
+
+export default App;
+```
+
+## SDS vs MUI
+
+The following props and options differ and how they function across the MUI Switch component and the SDS InputToggle component:
+
+- `size`: Has no effect in SDS
+
+- `color`: Has no effect in SDS
+
+- `onLabel` and `offLabel`: These are SDS-specific props. The toggle prints one of them inside the track depending on its state, which is why it is wider than a MUI Switch. Longer words may need a larger `width`.
+
+- `value`: Managed by SDS. The component sets it to the active label so the track can render that text, so passing your own `value` replaces the visible on/off text.
+
+- `checked`: Optional. Without it the toggle keeps its own state; pass it (with `onChange`) to control the toggle from your application.
+
+- The `required` prop is available for both the MUI and SDS components.
+
+## MUI Documentation
+
+Documentation for the underlying MUI component can be found [here](https://mui.com/material-ui/react-switch/).
+
+## Props
+
+Any custom SDS props and MUI props required for implementation are found on the table below. See the MUI documentation for additional optional props.
+
+| Name       | Type              | Default | Description                                                                                          |
+| ---------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `checked`  | `boolean`         | -       | Controls the toggle. Omit it and the component tracks its own state internally.                      |
+| `disabled` | `boolean`         | `false` | If `true`, the component is disabled.                                                                |
+| `offLabel` | `string`          | `"Off"` | The text displayed within the InputToggle when it's off.                                             |
+| `onLabel`  | `string`          | `"On"`  | The text displayed within the InputToggle when it's on.                                              |
+| `onChange` | `(event) => void` | -       | Called whenever the user toggles the component, in either direction.                                 |
+| `width`    | `number`          | `62`    | Controls the width of the InputToggle element, in pixels. Increase it when custom labels do not fit. |