@czi-sds/mcp 0.16.0 → 0.18.0

package/data/component-docs/List.md

@@ -0,0 +1,300 @@
+# List
+
+A list is three components: **List** for the `ul` or `ol` element, **ListItem** for each entry, and **ListSubheader** for the optional heading above them. All three wrap their MUI counterparts, so any MUI prop passes straight through.
+
+## Import
+
+**React TypeScript**
+
+```tsx
+import {
+  List,
+  ListItem,
+  ListItemLabel,
+  ListSubheader,
+} from "@czi-sds/components";
+```
+
+## Code examples
+
+### Unordered list
+
+An unordered list with a subheader. Neither the List nor the items need any props for this shape.
+
+**Example: UnorderedList**
+
+```tsx
+// An unordered list is the default: no props needed on List or ListItem. The
+// subheader goes through MUI's subheader prop, with disableSticky so it scrolls
+// with the content.
+
+import { List, ListItem, ListSubheader } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app" style={{ maxWidth: "460px" }}>
+      <List
+        subheader={
+          <ListSubheader disableSticky>Before you upload</ListSubheader>
+        }
+      >
+        <ListItem>Files must be gzipped FASTQ or BAM.</ListItem>
+        <ListItem>Every sample needs a unique identifier.</ListItem>
+        <ListItem>
+          Reads shorter than 30 bases are dropped during processing, so trim
+          them beforehand if you want to keep them.
+        </ListItem>
+      </List>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Ordered list
+
+The same list numbered, with `ordered` on the List and on every item.
+
+**Example: OrderedList**
+
+```tsx
+// ordered has to go on both the List and every ListItem: the List switches the
+// element to ol and starts the counter, and each item increments it and draws
+// its own number.
+
+import { List, ListItem, ListSubheader } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app" style={{ maxWidth: "460px" }}>
+      <List
+        ordered
+        subheader={
+          <ListSubheader disableSticky>Running an analysis</ListSubheader>
+        }
+      >
+        <ListItem ordered>Pick the samples you want to include.</ListItem>
+        <ListItem ordered>Choose a reference genome.</ListItem>
+        <ListItem ordered>Start the run and wait for the report.</ListItem>
+      </List>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Nested ordered list
+
+Nesting a List inside an ordered item numbers the sub-items against their parent, so they read 1.1. and 1.2.
+
+**Example: NestedOrderedList**
+
+```tsx
+// Nested numbering comes from a CSS counter, so sub-items read 1.1., 1.2., and
+// so on. The nested List has to live inside a single wrapper element, otherwise
+// it becomes a sibling of the item's text instead of a child of it.
+
+import { List, ListItem } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app" style={{ maxWidth: "460px" }}>
+      <List ordered>
+        <ListItem ordered marginBottom="s">
+          <span>
+            Prepare your data
+            <List ordered>
+              <ListItem ordered>Upload the raw reads.</ListItem>
+              <ListItem ordered>Attach the sample metadata.</ListItem>
+            </List>
+          </span>
+        </ListItem>
+        <ListItem ordered marginBottom="s">
+          <span>
+            Configure the pipeline
+            <List ordered>
+              <ListItem ordered>Choose a reference genome.</ListItem>
+              <ListItem ordered>Set the quality thresholds.</ListItem>
+            </List>
+          </span>
+        </ListItem>
+        <ListItem ordered>Start the run.</ListItem>
+      </List>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Sizes and spacing
+
+The type scale, each size with the item spacing it pairs with. Both props sit on the items, so one list can mix sizes.
+
+**Example: ListSizes**
+
+```tsx
+// fontSize sets the body type scale on each item, and marginBottom sets the gap
+// below it. Both live on ListItem, not on List, so a list can mix sizes.
+
+import { List, ListItem } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app">
+      <List>
+        <ListItem fontSize="l" marginBottom="s">
+          fontSize=&quot;l&quot;, marginBottom=&quot;s&quot;
+        </ListItem>
+        <ListItem fontSize="m" marginBottom="s">
+          fontSize=&quot;m&quot;, marginBottom=&quot;s&quot;
+        </ListItem>
+        <ListItem fontSize="s" marginBottom="xs">
+          fontSize=&quot;s&quot;, marginBottom=&quot;xs&quot; (the defaults)
+        </ListItem>
+        <ListItem fontSize="xs" marginBottom="xs">
+          fontSize=&quot;xs&quot;, marginBottom=&quot;xs&quot;
+        </ListItem>
+        <ListItem fontSize="xxs" marginBottom="xs">
+          fontSize=&quot;xxs&quot;, marginBottom=&quot;xs&quot;
+        </ListItem>
+        <ListItem fontSize="xxxs" marginBottom="xxs">
+          fontSize=&quot;xxxs&quot;, marginBottom=&quot;xxs&quot;
+        </ListItem>
+      </List>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Items with labels
+
+ListItemLabel makes the leading term semibold, which suits lists that define or name things.
+
+**Example: ListWithLabels**
+
+```tsx
+// ListItemLabel is a semibold span for the term at the start of an item, so
+// definition-style lists stay readable without hand-rolled font weights.
+
+import { List, ListItem, ListItemLabel } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app" style={{ maxWidth: "460px" }}>
+      <List>
+        <ListItem fontSize="s">
+          <span>
+            <ListItemLabel>Draft</ListItemLabel> Only you can see the dataset.
+          </span>
+        </ListItem>
+        <ListItem fontSize="s">
+          <span>
+            <ListItemLabel>Private</ListItemLabel> Everyone in your collection
+            can see the dataset.
+          </span>
+        </ListItem>
+        <ListItem fontSize="s">
+          <span>
+            <ListItemLabel>Published</ListItemLabel> The dataset is visible to
+            anyone with the link, and the version is frozen.
+          </span>
+        </ListItem>
+      </List>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## How the pieces fit together
+
+- `ordered` belongs on both the List and every ListItem. On the List it swaps the element to `ol` and starts the counter; on each item it increments the counter and draws the number. An `ol` whose items are missing the prop still renders bullets.
+
+- Markers are drawn by the item's `::before` pseudo-element rather than the browser's own list marker, and are always semibold. Bullets sit 8px from the text, numbers 6px.
+
+- Numbers come from a CSS counter, so a list nested inside an ordered item numbers itself 1.1., 1.2., and so on, to any depth.
+
+- Nested lists have to sit inside a single wrapper element together with the parent item's text. A ListItem is a flex row, so a bare _text plus List_ pair would lay the two out side by side.
+
+- Items align their marker to the top of the text, so wrapped copy keeps the bullet or number on the first line.
+
+- The List carries no padding of its own, so items line up flush with the surrounding text instead of the browser's default indent.
+
+- A subheader renders as an `li` without a marker, in `fontHeaderM`, 16px above the first item. That gap is effectively fixed; see `marginBottom` in the List table below.
+
+- Sizing and spacing live on ListItem, not on List, so nothing is inherited down. A list of six items at `fontSize` `"m"` needs the prop on all six.
+
+- Because the markers are CSS content and the browser's own list style is turned off, Safari and VoiceOver stop treating the element as a list. Add `role="list"` to the List when that matters.
+
+## Sizes and spacing
+
+The pairing below is the one the designs use, and the one the [Storybook story](https://chanzuckerberg.github.io/sci-components/?path=/story/components-list--default) demonstrates. Set both props on each item.
+
+| fontSize | Type                               | marginBottom | Gap below the item |
+| -------- | ---------------------------------- | ------------ | ------------------ |
+| `"l"`    | `fontBodyL`, 18px / 16px narrow    | `"s"`        | 8px                |
+| `"m"`    | `fontBodyM`, 16px / 14px narrow    | `"s"`        | 8px                |
+| `"s"`    | `fontBodyS`, 14px                  | `"xs"`       | 6px                |
+| `"xs"`   | `fontBodyXs`, 13px                 | `"xs"`       | 6px                |
+| `"xxs"`  | `fontBodyXxs`, 12px                | `"xs"`       | 6px                |
+| `"xxxs"` | `fontBodyXxxs`, 11px / 12px narrow | `"xxs"`      | 4px                |
+
+## List
+
+### 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/List/index.tsx).
+
+### Props
+
+Any custom SDS props and MUI props required for implementation are found on the table below. See the [MUI documentation](https://mui.com/material-ui/api/list/) for additional optional props.
+
+| Name             | Type                                                     | Default          | Description                                                                                                                                                                                                                                                                                                                                                              |
+| ---------------- | -------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ordered`        | `boolean`                                                | `false`          | Renders an `"ol"` element and starts the numbering counter. `false` renders a `"ul"`. Pass it to each ListItem as well, otherwise the items still draw bullets.                                                                                                                                                                                                          |
+| `subheader`      | `ReactNode`                                              | `undefined`      | The heading rendered above the items, normally a ListSubheader. Comes from MUI.                                                                                                                                                                                                                                                                                          |
+| `marginBottom`   | `"xxxs"` \| `"xxs"` \| `"xs"` \| `"s"` \| `"m"` \| `"l"` | `"s"`            | Sets the gap below the subheader, not below the list: 8px for `"xxxs"`, 12px through `"xxs"` to `"s"`, 16px for `"m"` and `"l"`. It collides with the 16px margin ListSubheader sets on itself at the same specificity, so the winner comes down to the order the styles were inserted and the prop is not dependable. Space the list itself with its container instead. |
+| `component`      | `ElementType`                                            | `"ul"` or `"ol"` | Overrides the element the list renders as, taking precedence over `ordered`. Reach for it only when the markup has to differ from the semantics.                                                                                                                                                                                                                         |
+| `disablePadding` | `boolean`                                                | `true`           | MUI's vertical padding is off by default. Pass `false` to bring back its 8px top and bottom padding.                                                                                                                                                                                                                                                                     |
+
+## ListItem
+
+### 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/List/components/ListItem/index.tsx).
+
+### Props
+
+Any custom SDS props and MUI props required for implementation are found on the table below. See the [MUI documentation](https://mui.com/material-ui/api/list-item/) for additional optional props.
+
+| Name           | Type                                                     | Default     | Description                                                                                                                                                               |
+| -------------- | -------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fontSize`     | `"xxxs"` \| `"xxs"` \| `"xs"` \| `"s"` \| `"m"` \| `"l"` | `"s"`       | The body type scale for this item. Set it on every item; it is not inherited from the List.                                                                               |
+| `marginBottom` | `"s"` \| `"xs"` \| `"xxs"`                               | `"xs"`      | The gap below this item: `"s"` is 8px, `"xs"` is 6px, `"xxs"` is 4px. It applies to the last item too, so drop the default when the list sits right above something else. |
+| `ordered`      | `boolean`                                                | `false`     | Draws a counter-based number instead of a bullet. It has to match the `ordered` prop on the parent List.                                                                  |
+| `children`     | `ReactNode`                                              | `undefined` | The item's content. Wrap it in a single element when the item holds more than a string, since the item lays its children out in a row.                                    |
+
+### ListItemLabel
+
+ListItemLabel, exported alongside ListItem, is a semibold span for the term at the start of an item. It adds 5px of space after itself, but keep an ordinary space in the copy as well, otherwise a screen reader reads the label and the sentence after it as one word.
+
+## ListSubheader
+
+### 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/List/components/ListSubheader/index.tsx).
+
+### Props
+
+ListSubheader adds no SDS props: it takes `fontHeaderM`, a 16px bottom margin, and the surrounding text color, then passes everything through to [MUI's ListSubheader](https://mui.com/material-ui/api/list-subheader/). The two props worth knowing are below.
+
+| Name             | Type      | Default | Description                                                                                                                                    |
+| ---------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `disableSticky`  | `boolean` | `false` | MUI pins the subheader to the top of a scrolling container. Pass it so the heading scrolls away with the list, which is what the designs show. |
+| `disableGutters` | `boolean` | `true`  | MUI's horizontal padding is off by default, keeping the heading flush with the items.                                                          |

package/data/component-docs/LoadingIndicator.md

@@ -0,0 +1,198 @@
+# LoadingIndicator
+
+## 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/LoadingIndicator/index.tsx).
+
+## Import
+
+**React TypeScript**
+
+```tsx
+import { LoadingIndicator } from "@czi-sds/components";
+```
+
+## Code examples
+
+### LoadingIndicator – Minimal
+
+Use the minimal variant when part of a page is still filling in, such as the body of an Accordion or the rows of a Table.
+
+**Example: LoadingIndicatorMinimal**
+
+```tsx
+// The minimal variant is body-sized text in secondary grey, for a region of a
+// page that is still filling in. sdsStyle is required; there is no default.
+
+import { LoadingIndicator } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app">
+      <LoadingIndicator sdsStyle="minimal" />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### LoadingIndicator – Tag
+
+Use the tag variant when a whole page or view has not arrived yet.
+
+**Example: LoadingIndicatorTag**
+
+```tsx
+// The tag variant is an accent-colored pill with all-caps text, for a whole
+// page or view that has not arrived yet.
+
+import { LoadingIndicator } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div className="app">
+      <LoadingIndicator sdsStyle="tag" />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Naming what is loading
+
+The two indicators below look identical, but the second announces "Loading cell types" instead of "Loading". Name the thing being loaded whenever more than one wait can be in flight.
+
+**Example: LoadingIndicatorAriaLabel**
+
+```tsx
+// aria-label changes only what a screen reader announces. The visible word
+// stays "Loading" either way, so use the label to name what is loading.
+
+import { LoadingIndicator } from "@czi-sds/components";
+
+function App() {
+  return (
+    <div
+      className="app"
+      style={{
+        alignItems: "flex-start",
+        display: "flex",
+        flexDirection: "column",
+        gap: "8px",
+      }}
+    >
+      <LoadingIndicator sdsStyle="minimal" />
+      <LoadingIndicator sdsStyle="minimal" aria-label="Loading cell types" />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Loading a region on demand
+
+Swapping the indicator in for the content it is standing in for, which is what gives the status region something to announce, and what gives the wait a visible end.
+
+**Example: LoadingIndicatorInContext**
+
+```tsx
+// Mount the indicator when the wait starts and unmount it when the content
+// arrives: the status region announces itself on mount. Removing it announces
+// nothing, so the content that replaces it carries the news.
+//
+// The component accepts no className or style, so any layout, centering
+// included, belongs on a wrapper around it.
+
+import {
+  Button,
+  fontBodyS,
+  getSemanticColors,
+  LoadingIndicator,
+  type CommonThemeProps,
+} from "@czi-sds/components";
+import styled from "@emotion/styled";
+import { useEffect, useRef, useState } from "react";
+
+const Surface = styled.div<CommonThemeProps>`
+  ${fontBodyS}
+
+  ${(props) => {
+    const semanticColors = getSemanticColors(props);
+
+    return `
+      border: 1px solid ${semanticColors?.base?.divider};
+      border-radius: 4px;
+      color: ${semanticColors?.base?.textPrimary};
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      height: 96px;
+      margin-bottom: 12px;
+      width: 320px;
+    `;
+  }}
+`;
+
+function App() {
+  const [loading, setLoading] = useState(false);
+  const timeout = useRef<ReturnType<typeof setTimeout>>();
+
+  useEffect(() => () => clearTimeout(timeout.current), []);
+
+  const load = () => {
+    setLoading(true);
+    timeout.current = setTimeout(() => setLoading(false), 2000);
+  };
+
+  return (
+    <div className="app">
+      <Surface>
+        {loading ? (
+          <LoadingIndicator sdsStyle="minimal" aria-label="Loading samples" />
+        ) : (
+          <span>4 samples ready</span>
+        )}
+      </Surface>
+
+      <Button sdsStyle="outline" sdsType="primary" onClick={load}>
+        Reload samples
+      </Button>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## Behavior notes
+
+- The component reads exactly two props, `sdsStyle` and `aria-label`, and ignores everything else. There is no `className`, `style`, `id`, `children`, or data attribute to pass, and no ref to take, so wrap it in an element of your own for layout, spacing, or centering.
+
+- The visible label is the hard-coded word _Loading_. It cannot be changed or translated, so a wait that needs different copy needs a line of your own text beside the indicator.
+
+- Both variants stand 32px tall and sit `inline-flex`, so they line up with adjacent text rather than filling their container.
+
+- Internally there is 4px of padding and nothing more. The 16px of clearance the spacing guideline above asks for is yours to add on the surrounding element.
+
+- The spinner is animated inside the SVG itself, not with CSS, so it keeps spinning under `prefers-reduced-motion` and there is no prop to stop it.
+
+- The label sits in a `role="status"`, `aria-live="polite"` region, so it announces itself when it mounts. Render it when the wait starts and unmount it when the wait ends: nothing is announced on removal, so the content that replaces it has to carry the result.
+
+## The two variants
+
+| sdsStyle    | Type                       | Color                                                                     | Spinner |
+| ----------- | -------------------------- | ------------------------------------------------------------------------- | ------- |
+| `"minimal"` | `fontBodyS`, sentence case | Text `base.textSecondary`, spinner `base.ornamentSecondary`, no fill      | 16px    |
+| `"tag"`     | `fontCapsXxxxs`, all caps  | Text and spinner `accent.foreground` on an `accent.surfaceSecondary` pill | 24px    |
+
+## Props
+
+The component takes no MUI props. Its full surface is the table below; any other prop is a type error.
+
+| Name         | Type                   | Default      | Description                                                                                                                                                                                           |
+| ------------ | ---------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sdsStyle`   | `"minimal"` \| `"tag"` | - (required) | Chooses between the two variants above. It has no default: leaving it out is a type error, and an indicator built without it renders unstyled.                                                        |
+| `aria-label` | `string`               | `undefined`  | Replaces what a screen reader announces for the status region, for example "Loading cell types". The visible text still reads "Loading". Without it, assistive technology announces the visible word. |