@czi-sds/mcp 0.16.0 → 0.17.0

package/data/component-docs/ButtonToggle.md

@@ -0,0 +1,397 @@
+# ButtonToggle
+
+## Source Code
+
+The component's source code in the SDS codebase can be found [here](https://github.com/chanzuckerberg/sci-components/tree/main/packages/components/src/core/ButtonToggle).
+
+## Import
+
+**React TypeScript**
+
+```tsx
+import { ButtonToggle } from "@czi-sds/components";
+```
+
+## Code examples
+
+### **Default ButtonToggle**
+
+This example has the minimum props needed for the ButtonToggle component. Because `sdsStage` is controlled, the on and off stages are driven from state.
+
+**Example: DefaultButtonToggle**
+
+```tsx
+import * as React from "react";
+import { ButtonToggle, Icon } from "@czi-sds/components";
+
+function App() {
+  const [toggle, setToggle] = React.useState(false);
+
+  return (
+    <div className="app">
+      <ButtonToggle
+        sdsStyle="outline"
+        sdsType="primary"
+        sdsStage={toggle ? "on" : "off"}
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+        onClick={() => setToggle((prev) => !prev)}
+      >
+        Label
+      </ButtonToggle>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### ButtonToggle styles
+
+This example shows the two styles a toggle is designed around, `"outline"` and `"minimal"`, in both stages. `sdsStyle` also accepts Button's `"solid"`, which has no toggle treatment of its own, so set one of these two explicitly rather than taking the inherited default.
+
+**Example: ButtonToggleStyles**
+
+```tsx
+// Toggles are designed around the outline and minimal styles. sdsStyle also
+// accepts Button's "solid", which has no toggle treatment of its own, so set one
+// of these two explicitly rather than taking the inherited default.
+//
+// sdsType is set explicitly for the same reason: the on stage resolves its colors
+// before Button applies its own default, so leaving it out draws the neutral
+// treatment over a button that is otherwise primary.
+//
+// The stages below are fixed rather than driven from state, so both can be seen
+// without clicking.
+
+import { ButtonToggle, Icon } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app" style={{ display: "flex", gap: "16px" }}>
+      <ButtonToggle
+        sdsStage="off"
+        sdsStyle="outline"
+        sdsType="primary"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Outline off
+      </ButtonToggle>
+
+      <ButtonToggle
+        sdsStage="on"
+        sdsStyle="outline"
+        sdsType="primary"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Outline on
+      </ButtonToggle>
+
+      <ButtonToggle
+        sdsStage="off"
+        sdsStyle="minimal"
+        sdsType="primary"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Minimal off
+      </ButtonToggle>
+
+      <ButtonToggle
+        sdsStage="on"
+        sdsStyle="minimal"
+        sdsType="primary"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Minimal on
+      </ButtonToggle>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### ButtonToggle types
+
+This example shows the two color schemes available through `sdsType`, which is what decides how the on stage reads: primary fills with the accent color, secondary stays neutral.
+
+**Example: ButtonToggleTypes**
+
+```tsx
+// The type decides what the on stage looks like: primary fills with the accent
+// color, secondary stays neutral. Both stages are shown for each.
+
+import { ButtonToggle, Icon } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app" style={{ display: "flex", gap: "16px" }}>
+      <ButtonToggle
+        sdsStage="off"
+        sdsStyle="outline"
+        sdsType="primary"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Primary off
+      </ButtonToggle>
+
+      <ButtonToggle
+        sdsStage="on"
+        sdsStyle="outline"
+        sdsType="primary"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Primary on
+      </ButtonToggle>
+
+      <ButtonToggle
+        sdsStage="off"
+        sdsStyle="outline"
+        sdsType="secondary"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Secondary off
+      </ButtonToggle>
+
+      <ButtonToggle
+        sdsStage="on"
+        sdsStyle="outline"
+        sdsType="secondary"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Secondary on
+      </ButtonToggle>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### ButtonToggle sizes
+
+This example shows the three sizes available through the `size` prop.
+
+**Example: ButtonToggleSizes**
+
+```tsx
+import { ButtonToggle, Icon } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div
+      className="app"
+      style={{ alignItems: "center", display: "flex", gap: "16px" }}
+    >
+      <ButtonToggle
+        size="large"
+        sdsStyle="outline"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Large
+      </ButtonToggle>
+
+      <ButtonToggle
+        size="medium"
+        sdsStyle="outline"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Medium
+      </ButtonToggle>
+
+      <ButtonToggle
+        size="small"
+        sdsStyle="outline"
+        startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+      >
+        Small
+      </ButtonToggle>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Icon-only ButtonToggle
+
+This example shows the form a toggle usually takes. Leaving `children` out is what makes it square, and since there is then no text for a screen reader to announce, each one needs an `aria-label`.
+
+**Example: ButtonToggleIconOnly**
+
+```tsx
+// Leaving children out is what makes a toggle square, and it is the form a
+// toggle usually takes. There is then no text for a screen reader to announce,
+// so each one needs an aria-label of its own.
+
+import { useState } from "react";
+import { ButtonToggle, Icon } from "@czi-sds/components";
+
+function App() {
+  const [labels, setLabels] = useState(true);
+  const [filters, setFilters] = useState(false);
+
+  return (
+    <div className="app" style={{ display: "flex", gap: "16px" }}>
+      <ButtonToggle
+        aria-label="Show labels"
+        sdsStage={labels ? "on" : "off"}
+        sdsStyle="outline"
+        sdsType="primary"
+        startIcon={<Icon sdsIcon="EyeOpen" sdsSize="s" />}
+        onClick={() => setLabels((previous) => !previous)}
+      />
+
+      <ButtonToggle
+        aria-label="Show filters"
+        sdsStage={filters ? "on" : "off"}
+        sdsStyle="outline"
+        sdsType="primary"
+        startIcon={<Icon sdsIcon="Filter" sdsSize="s" />}
+        onClick={() => setFilters((previous) => !previous)}
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### ButtonToggle on a dark background
+
+This example shows `backgroundAppearance="dark"`, which tells the toggle it sits on a dark surface so it can pick colors with enough contrast in both stages. The toggle paints no background of its own, so the panel is supplied alongside the prop.
+
+**Example: ButtonToggleOnADarkBackground**
+
+```tsx
+// backgroundAppearance tells the toggle which surface it is on so it can pick
+// colors with enough contrast, in both stages. It paints no background of its
+// own, so the dark panel below is the page's to supply.
+
+import {
+  ButtonToggle,
+  Icon,
+  getCorners,
+  getSemanticColors,
+  getSpaces,
+} from "@czi-sds/components";
+import { useTheme } from "@mui/material/styles";
+
+function App() {
+  const theme = useTheme();
+  const corners = getCorners({ theme });
+  const semanticColors = getSemanticColors({ theme });
+  const spaces = getSpaces({ theme });
+
+  return (
+    <div className="app">
+      <div
+        style={{
+          alignItems: "center",
+          backgroundColor: semanticColors?.base?.backgroundPrimaryDark,
+          borderRadius: corners?.m,
+          display: "flex",
+          gap: spaces?.l,
+          padding: spaces?.xl,
+        }}
+      >
+        <ButtonToggle
+          backgroundAppearance="dark"
+          sdsStage="off"
+          sdsStyle="outline"
+          sdsType="primary"
+          startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+        >
+          Off
+        </ButtonToggle>
+
+        <ButtonToggle
+          backgroundAppearance="dark"
+          sdsStage="on"
+          sdsStyle="outline"
+          sdsType="primary"
+          startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+        >
+          On
+        </ButtonToggle>
+
+        <ButtonToggle
+          backgroundAppearance="dark"
+          sdsStage="on"
+          sdsStyle="minimal"
+          sdsType="primary"
+          startIcon={<Icon sdsIcon="LinesHorizontal3" sdsSize="s" />}
+        >
+          Minimal on
+        </ButtonToggle>
+      </div>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Toggles in a ButtonGroup
+
+This example shows icon-only toggles collected into a ButtonGroup, each tracking its own stage.
+
+**Example: ButtonToggleGroup**
+
+```tsx
+import * as React from "react";
+import { ButtonGroup, ButtonToggle, Icon } from "@czi-sds/components";
+
+const TOGGLES = [
+  { icon: "Search", label: "Search" },
+  { icon: "Copy", label: "Copy" },
+  { icon: "Code", label: "Code" },
+] as const;
+
+function App() {
+  const [active, setActive] = React.useState<Record<string, boolean>>({});
+
+  return (
+    <div className="app">
+      <ButtonGroup sdsType="secondary">
+        {TOGGLES.map(({ icon, label }) => (
+          <ButtonToggle
+            key={label}
+            aria-label={label}
+            sdsStyle="outline"
+            sdsType="secondary"
+            sdsStage={active[label] ? "on" : "off"}
+            startIcon={<Icon sdsIcon={icon} sdsSize="s" />}
+            onClick={() =>
+              setActive((prev) => ({ ...prev, [label]: !prev[label] }))
+            }
+          />
+        ))}
+      </ButtonGroup>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## MUI Documentation
+
+Documentation for the underlying MUI component can be found [here](https://mui.com/material-ui/react-button/).
+
+## 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                                                                                                                                                                                                                                                                                                                                                                                          |
+| ---------------------- | --------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `startIcon`            | `ReactElement`                          | -                   | **Required.** The icon displayed within the component. Pass the SDS Icon component, for example `<Icon sdsIcon="Search" sdsSize="s" />`.                                                                                                                                                                                                                                                             |
+| `sdsStage`             | `"on"` \| `"off"`                       | `"off"`             | Controls the toggle stage. The component is fully controlled, so keep this value in state and update it from `onClick`.                                                                                                                                                                                                                                                                              |
+| `sdsStyle`             | `"solid"` \| `"outline"` \| `"minimal"` | `"solid"`           | Style of the button. ButtonToggle inherits Button's default of `"solid"`, but toggles are designed around `"outline"` and `"minimal"`, so set one of those explicitly.                                                                                                                                                                                                                               |
+| `sdsType`              | `"primary" \| "secondary"`              | `"primary"`         | Color scheme of the button. Primary uses the accent color in the on stage, secondary stays neutral. Set it explicitly: the on stage resolves its colors before Button applies this default, so an omitted value draws the neutral treatment over a button that is otherwise primary. Button's `"destructive"` is inherited by the type but has no on-stage treatment, so it should not be used here. |
+| `size`                 | `"small"` \| `"medium"` \| `"large"`    | `"large"`           | Size of the button.                                                                                                                                                                                                                                                                                                                                                                                  |
+| `disabled`             | `boolean`                               | `false`             | Disables the toggle button when set to `true`.                                                                                                                                                                                                                                                                                                                                                       |
+| `backgroundAppearance` | `"matchBackground"` \| `"dark"`         | `"matchBackground"` | Button's prop, telling the toggle which surface it sits on so it can pick colors with enough contrast.                                                                                                                                                                                                                                                                                               |
+| `children`             | `ReactNode`                             | -                   | Text beside the icon. A toggle is normally icon-only, and leaving this out is what makes it square.                                                                                                                                                                                                                                                                                                  |
+| `onClick`              | `(event: React.MouseEvent) => void`     | -                   | Callback fired when the button is clicked.                                                                                                                                                                                                                                                                                                                                                           |
+
+ButtonToggle always renders with `backgroundOnHover` enabled and ignores `endIcon`, which is reserved for the toggle's own styling.

package/data/component-docs/Callout.md

@@ -0,0 +1,268 @@
+# Callout
+
+## 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/Callout/index.tsx).
+
+## Import
+
+**React TypeScript**
+
+```tsx
+import { Callout, CalloutTitle } from "@czi-sds/components";
+```
+
+## Code examples
+
+### Default Callout
+
+This example has the minimum props needed for the Callout component. Only `intent` is required, but a Callout with no `title` or `body` renders as an empty box, so both are given here.
+
+**Example: DefaultCallout**
+
+```tsx
+// Most minimal Callout (just has the basic requirements)
+
+import { Callout } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app">
+      <Callout
+        intent="info"
+        title="Callout box"
+        body="The Callout component is a versatile UI element designed to draw attention to important information or messages within your interface."
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Callout intents
+
+This example shows the five intents, each with the icon the Callout picks by default.
+
+**Example: CalloutIntents**
+
+```tsx
+// Every intent, each with the icon the Callout picks by default
+
+import { Callout } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app">
+      <Callout
+        intent="info"
+        title="Info"
+        body="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+      />
+      <Callout
+        intent="accent"
+        title="Accent"
+        body="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+      />
+      <Callout
+        intent="positive"
+        title="Positive"
+        body="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+      />
+      <Callout
+        intent="notice"
+        title="Notice"
+        body="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+      />
+      <Callout
+        intent="negative"
+        title="Negative"
+        body="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Expandable Callout
+
+The Expandable Callout component provides an interactive and space-efficient way to present information. By default, it displays a brief summary, however, users can expand it to reveal more detailed content, similar to an accordion. This feature is particularly useful for sharing additional context or insights while keeping the initial interface clutter-free. The extra content is passed as `children`, and `sdsStage` sets whether the Callout starts open or closed.
+
+**Example: ExpandableCallout**
+
+```tsx
+// Expandable Callout: children are the extra content revealed by the chevron
+
+import { Callout } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app">
+      <Callout
+        intent="notice"
+        sdsStyle="expandable"
+        sdsStage="closed"
+        title="Attention Required"
+        body="The Callout serves as a visual alert to draw immediate attention to information that requires action or consideration."
+      >
+        Use the expandable style strategically, and only when there really is
+        extra content to reveal. The chevron is rendered either way, so an
+        expandable Callout with no children toggles to an empty section.
+      </Callout>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Dismissible Callout
+
+The dismissible Callout variant provides users with the ability to dismiss it at their convenience. It includes a close button located in the top right corner, offering a familiar interaction pattern for users to remove the Callout from view. The Callout hides itself when that button is clicked, so `onClose` is for keeping your own state in sync; setting `dismissed` back to `false` is what brings the Callout back.
+
+**Example: DismissibleCallout**
+
+```tsx
+// Closable Callout
+
+import { useState } from "react";
+import { Button, Callout } from "@czi-sds/components";
+
+function App() {
+  const [dismissed, setDismissed] = useState(false);
+
+  return (
+    <div className="app">
+      <Callout
+        intent="negative"
+        sdsStyle="dismissible"
+        dismissed={dismissed}
+        onClose={() => setDismissed(true)}
+        title="An Error Occurred"
+        body="The Error Callout is a crucial component for communicating critical errors or issues to users."
+      />
+      {dismissed && (
+        <Button onClick={() => setDismissed(false)} sdsType="primary">
+          Reset Callout
+        </Button>
+      )}
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Callout with a custom icon
+
+This example replaces the icon that the `intent` would otherwise choose. The `icon` prop takes either an SDS icon name or an element.
+
+**Example: CalloutWithACustomIcon**
+
+```tsx
+// Replacing the intent's default icon with any SDS icon
+
+import { Callout } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app">
+      <Callout
+        intent="accent"
+        icon="Bacteria"
+        title="Custom icon"
+        body="Pass an icon name to swap the icon the intent would otherwise pick."
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Callout with auto dismiss
+
+This example dismisses itself after four seconds. Pass `true` instead of a number to use the default delay of `8000` milliseconds.
+
+**Example: CalloutWithAutoDismiss**
+
+```tsx
+// The Callout dismisses itself once the timeout elapses. Remounting it with a
+// new key restarts the countdown.
+
+import { useState } from "react";
+import { Button, Callout } from "@czi-sds/components";
+
+function App() {
+  const [runId, setRunId] = useState(0);
+
+  return (
+    <div className="app">
+      <Callout
+        key={runId}
+        intent="positive"
+        autoDismiss={4000}
+        title="Saved"
+        body="This Callout disappears on its own after four seconds."
+      />
+      <Button onClick={() => setRunId((prev) => prev + 1)} sdsType="primary">
+        Show again
+      </Button>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## SDS vs MUI
+
+The SDS Callout component is built upon the MUI Alert component (as is the SDS Notification component), but there are some important differences:
+
+- **Color:** SDS's Callout component has its own `intent` prop designed for setting both the color and default icon, and takes the values of `"accent"`, `"info"`, `"negative"`, `"notice"`, or `"positive"`. MUI's Alert instead uses the `severity` prop for this purpose (`severity` can also be used for SDS's Notification, and will take the same values as `intent`; this is not recommended)
+
+- **Title and body:** Rather than composing an AlertTitle and text as children the way MUI's Alert does, SDS's Callout takes its content through the `title` and `body` props and renders the stylized CalloutTitle for you. Children are reserved for the extra content of an expandable Callout, and are ignored by the other styles.
+
+- **Expanding and closing:** Both behaviors come from the `sdsStyle` prop rather than from separate props. Setting it to `"expandable"` adds a chevron in the top right that toggles the children in and out of view, and setting it to `"dismissible"` adds a close button that hides the Callout and fires `onClose`. An expandable Callout should only be used when there really is extra content to reveal, since the chevron is rendered either way. SDS uses MUI's Alert `action` prop under the hood, in case there is a need to further override the behavior.
+
+- **Transitions:** SDS's Callout uses the Grow transition component by default
+
+- **Icons:** Like with MUI's Alert, SDS's Callout also shows an icon to the left of the title text. It is chosen automatically from the `intent` (see the first bullet) and can be overridden with the `icon` prop, which takes either the name of an SDS icon or a custom SVG element:
+
+**React TypeScript**
+
+```tsx
+icon="Book"
+icon={<Icon sdsSize="s" sdsIcon="Book" />}
+```
+
+Additionally, setting `icon={false}` has no effect, and `iconMapping` does not work to change icons associated to `intent` or `severity`.
+
+- **Variants:** The `variant` prop is not available for SDS's Callout component.
+
+## MUI Documentation
+
+Documentation for the underlying MUI Alert component can be found [here](https://mui.com/material-ui/react-alert/).
+
+## 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                                                                                                                                                                                                                                                                                   |
+| -------------- | -------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `intent`       | `"accent"` \| `"info"` \| `"negative"` \| `"notice"` \| `"positive"` | -              | **Required.** Sets both the color of the component and the icon it defaults to.                                                                                                                                                                                                               |
+| `sdsStyle`     | `"persistent"` \| `"expandable"` \| `"dismissible"`                  | `"persistent"` | Defines the style of the Callout: - `"persistent"`: Cannot be closed. - `"expandable"`: Includes a chevron icon that toggles the children in and out of view. - `"dismissible"`: Includes an “x” icon for manual dismissal.                                                                   |
+| `title`        | `string`                                                             | -              | The Callout title.                                                                                                                                                                                                                                                                            |
+| `body`         | `ReactNode`                                                          | -              | The Callout body, shown beneath the title.                                                                                                                                                                                                                                                    |
+| `children`     | `ReactNode`                                                          | -              | Extra content revealed when an expandable Callout is open. The other styles ignore `children`, so use `body` for the main message.                                                                                                                                                            |
+| `extraContent` | `ReactNode`                                                          | -              | The same slot as `children`, for callers that would rather pass it as a prop. Both render when both are given, `children` first.                                                                                                                                                              |
+| `hideTitle`    | `boolean`                                                            | `false`        | If set to `true`, hides the Callout title.                                                                                                                                                                                                                                                    |
+| `hideBody`     | `boolean`                                                            | `false`        | If set to `true`, hides the Callout body and centers the icon against the remaining content.                                                                                                                                                                                                  |
+| `icon`         | `SDSIcon \| React.ReactElement<CustomSVGProps>`                      | -              | Icon displayed to the left of the Callout title, given either as an SDS icon name or as an element. Defaults to the icon for the current `intent`: `"CheckCircle"` for `"positive"`, `"InfoCircle"` for `"info"`, and `"ExclamationMarkCircle"` for `"accent"`, `"notice"`, and `"negative"`. |
+| `sdsIconProps` | `Partial<IconProps>`                                                 | -              | Props forwarded to the Icon component when `icon` is given as a name.                                                                                                                                                                                                                         |
+| `sdsStage`     | `"open" \| "closed"`                                                 | `"open"`       | The stage an expandable Callout starts in. It is only the initial value; the chevron takes over from there.                                                                                                                                                                                   |
+| `dismissed`    | `boolean`                                                            | -              | Hides the Callout when set to `true`. Changing it back to `false` brings the Callout back, which is how a dismissed Callout is restored.                                                                                                                                                      |
+| `autoDismiss`  | `boolean \| number`                                                  | -              | Dismisses the Callout on a timer. A number sets the delay in milliseconds, and `true` uses `8000`. Leave it unset to keep the Callout visible until it is dismissed another way.                                                                                                              |
+| `onClose`      | `(event: React.SyntheticEvent) => void`                              | -              | Callback fired when the Callout is closed. The Callout hides itself regardless, so use this to sync your own state rather than to perform the hiding.                                                                                                                                         |