@czi-sds/mcp 0.16.0 → 0.18.0

package/data/component-docs/TooltipCondensed.md

@@ -0,0 +1,203 @@
+# TooltipCondensed
+
+## 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/TooltipCondensed/index.tsx).
+
+## Import
+
+**React TypeScript**
+
+```tsx
+import { TooltipCondensed } from "@czi-sds/components";
+```
+
+## Code examples
+
+### Default TooltipCondensed
+
+One line of text on a cell, which is all a condensed tooltip needs. Move across the cell to see it follow the cursor, the behaviour the component locks in and the reason it suits a chart.
+
+**Example: DefaultTooltipCondensed**
+
+```tsx
+// The least a condensed tooltip needs: one line of text on something the pointer
+// passes over. Move across the cell to see it follow the cursor, which is the
+// behaviour the component locks in and the reason it suits a chart.
+
+import {
+  TooltipCondensed,
+  fontBodyXs,
+  getSemanticColors,
+  getSpaces,
+  type CommonThemeProps,
+} from "@czi-sds/components";
+import styled from "@emotion/styled";
+
+const Stage = styled.div<CommonThemeProps>`
+  ${(props) => {
+    const spaces = getSpaces(props);
+
+    return `
+      display: flex;
+      justify-content: center;
+      padding: ${spaces?.xl}px 0;
+    `;
+  }}
+`;
+
+const Cell = styled.div<CommonThemeProps>`
+  ${fontBodyXs}
+
+  ${(props) => {
+    const semanticColors = getSemanticColors(props);
+    const spaces = getSpaces(props);
+
+    return `
+      border: 1px solid ${semanticColors?.base?.divider};
+      border-radius: 4px;
+      color: ${semanticColors?.base?.textPrimary};
+      cursor: default;
+      padding: ${spaces?.s}px ${spaces?.m}px;
+    `;
+  }}
+`;
+
+function App() {
+  return (
+    <div className="app">
+      <Stage>
+        <TooltipCondensed title="1,284 cells">
+          <Cell>A point in a chart</Cell>
+        </TooltipCondensed>
+      </Stage>
+    </div>
+  );
+}
+
+export default App;
+```
+
+### TooltipCondensed with indicator
+
+Two condensed tooltips on a table cell, each with a coloured dot tying it to the value it describes. Both follow the pointer as it moves across the cell.
+
+**Example: TooltipCondensedWithIndicator**
+
+```tsx
+// TooltipCondensed is the label-sized tooltip for dense surfaces: charts, table
+// cells, anywhere a full sentence would be too much. It follows the cursor instead
+// of anchoring to the element, and it locks that down: followCursor, placement,
+// arrow, and the enter and leave delays are all applied after your props, so passing
+// placement or arrow here changes nothing.
+//
+// indicator draws a 12px dot before the text, coloured by indicatorColor, for tying
+// the tooltip to a series in a chart. indicatorColor takes a raw CSS colour rather
+// than an SDS name, so read the one you want off the theme. Without it the dot is
+// still laid out, just invisible.
+
+import {
+  TooltipCondensed,
+  fontBodyXs,
+  getSemanticColors,
+  getSpaces,
+  type CommonThemeProps,
+} from "@czi-sds/components";
+import styled from "@emotion/styled";
+import { useTheme } from "@mui/material/styles";
+
+const Stage = styled.div<CommonThemeProps>`
+  ${(props) => {
+    const spaces = getSpaces(props);
+
+    return `
+      display: flex;
+      gap: ${spaces?.xxl}px;
+      justify-content: center;
+      padding: ${spaces?.xl}px 0;
+    `;
+  }}
+`;
+
+const Cell = styled.div<CommonThemeProps>`
+  ${fontBodyXs}
+
+  ${(props) => {
+    const semanticColors = getSemanticColors(props);
+    const spaces = getSpaces(props);
+
+    return `
+      align-items: center;
+      border: 1px solid ${semanticColors?.base?.divider};
+      border-radius: 4px;
+      color: ${semanticColors?.base?.textPrimary};
+      cursor: default;
+      display: flex;
+      gap: ${spaces?.xs}px;
+      padding: ${spaces?.s}px ${spaces?.m}px;
+    `;
+  }}
+`;
+
+function App() {
+  const theme = useTheme();
+  const semanticColors = getSemanticColors({ theme });
+
+  return (
+    <div className="app">
+      <Stage>
+        <TooltipCondensed
+          indicator
+          indicatorColor={semanticColors?.info?.fillPrimary}
+          title="1,284 cells"
+        >
+          <Cell>Hover a data point</Cell>
+        </TooltipCondensed>
+
+        <TooltipCondensed
+          indicator
+          indicatorColor={semanticColors?.negative?.fillPrimary}
+          title="12 failed QC"
+        >
+          <Cell>Hover a failing point</Cell>
+        </TooltipCondensed>
+      </Stage>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## SDS vs MUI
+
+TooltipCondensed is the SDS Tooltip with tighter padding and a fixed set of behaviors, for labelling something in a dense surface such as a chart or a table cell. It takes every Tooltip prop, including `subtitle` and `componentSlot`, and adds two of its own:
+
+- `indicator`: draws a 12px round dot before the text, for tying the tooltip to a series in a chart or a colour in a legend.
+
+- `indicatorColor`: the dot's colour, given as a CSS colour rather than an SDS name, so read the one you want off the theme. With `indicator` but no colour the dot still takes up its space and stays invisible.
+
+Five props are applied after yours and so cannot be changed: `followCursor`, which is what makes the tooltip track the pointer rather than anchor to the element; `placement="right-end"`; `arrow={false}`; and `enterDelay` and `leaveDelay` of 50ms each, which keep it from flickering as the pointer crosses a dense chart. Passing a placement or an arrow of your own is silently ignored.
+
+## MUI Documentation
+
+Documentation for the underlying MUI component can be found [here](https://mui.com/material-ui/react-tooltip/).
+
+## Behavior and accessibility
+
+- Because it follows the cursor, this tooltip is a pointer-only affordance. It still opens on focus, but it then appears wherever the pointer happens to be, so anything it says has to exist elsewhere for a keyboard or screen reader user.
+
+- Keep the text to a label: a value, a count, a name. Full sentences belong in a Tooltip, and rows of numbers belong in a TooltipTable passed through `componentSlot`.
+
+- The dot carries no meaning on its own. Whatever it encodes needs to be legible from the text beside it too.
+
+## 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                                                                                  |
+| ---------------- | ----------- | ------- | -------------------------------------------------------------------------------------------- |
+| `title`          | `ReactNode` | -       | The label to show. Pass `null` when the content is coming through `componentSlot` instead.   |
+| `indicator`      | `boolean`   | `false` | Draws a 12px round dot before the text.                                                      |
+| `indicatorColor` | `string`    | -       | The dot's colour, as a CSS colour. Without it the dot occupies its space but cannot be seen. |
+| `componentSlot`  | `ReactNode` | -       | Inherited from Tooltip, and how a TooltipTable is placed inside a condensed tooltip.         |

package/data/component-docs/TooltipTable.md

@@ -0,0 +1,145 @@
+# TooltipTable
+
+## 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/TooltipTable/index.tsx).
+
+## Import
+
+**React TypeScript**
+
+```tsx
+import { TooltipTable } from "@czi-sds/components";
+```
+
+## Code examples
+
+### Default TooltipTable
+
+The table inside a condensed tooltip in the lighter scheme, which is what pairs it with a chart or a table cell that the pointer moves across.
+
+**Example: DefaultTooltipTable**
+
+```tsx
+// TooltipTable is not a tooltip. It is the content (a two-column table of labels
+// and values, grouped into sections) that goes inside one.
+//
+// It belongs in componentSlot rather than title, because title wraps whatever it is
+// given in a paragraph, and a table inside a paragraph is invalid HTML that React
+// complains about. Pair it with TooltipCondensed so the table follows the cursor,
+// which is how it is meant to behave over a chart or a table cell.
+//
+// The table asks for at least 224px and the tooltip caps out at 250px, so the two
+// only just fit. Long labels are what break the layout first, so keep them short.
+
+import {
+  TooltipCondensed,
+  TooltipTable,
+  fontBodyXs,
+  getSemanticColors,
+  getSpaces,
+  type CommonThemeProps,
+} from "@czi-sds/components";
+import styled from "@emotion/styled";
+
+const DATA = [
+  {
+    dataRows: [
+      { label: "Cells", value: "1,284" },
+      { label: "Median genes", value: "2,105" },
+      { label: "Mito. reads", value: "4.2%" },
+    ],
+    label: "Sample",
+  },
+  {
+    dataRows: [
+      { label: "Depth", value: "34x" },
+      { label: "Duplicates", value: "8.1%" },
+    ],
+    label: "Sequencing",
+  },
+];
+
+const Stage = styled.div<CommonThemeProps>`
+  ${(props) => {
+    const spaces = getSpaces(props);
+
+    return `
+      display: flex;
+      justify-content: center;
+      padding: ${spaces?.xl}px 0;
+    `;
+  }}
+`;
+
+const Cell = styled.div<CommonThemeProps>`
+  ${fontBodyXs}
+
+  ${(props) => {
+    const semanticColors = getSemanticColors(props);
+    const spaces = getSpaces(props);
+
+    return `
+      border: 1px solid ${semanticColors?.base?.divider};
+      border-radius: 4px;
+      color: ${semanticColors?.base?.textPrimary};
+      cursor: default;
+      padding: ${spaces?.s}px ${spaces?.m}px;
+    `;
+  }}
+`;
+
+function App() {
+  return (
+    <div className="app">
+      <Stage>
+        <TooltipCondensed
+          componentSlot={<TooltipTable data={DATA} itemAlign="right" />}
+          title={null}
+        >
+          <Cell>Hover for the sample summary</Cell>
+        </TooltipCondensed>
+      </Stage>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## SDS vs MUI
+
+TooltipTable is not a tooltip. It is the content that goes inside one: a two-column table of labels and values built on MUI's Table, exported as `TooltipTable` and named `TooltipTableContent` in the source. It has no trigger, no hover behavior and no popper of its own, so it does nothing on its own. Pass it to a tooltip's `componentSlot` and let the tooltip do the showing. What it adds:
+
+- `data`: the sections. Each one takes a `label`, a list of `dataRows` of label and value, and an optional `disabled` flag. Sections are separated by a divider, in the order given.
+
+- `itemAlign`: whether the values sit at the right of their column, which lines numbers up, or at the left.
+
+- `showSectionHeader`: whether the section labels are drawn at all. The dividers stay either way.
+
+- `contentAlert`: a line above the whole table, as a string or an element, for a caveat about the numbers below it.
+
+## MUI Documentation
+
+Documentation for the underlying MUI component can be found [here](https://mui.com/material-ui/react-table/).
+
+## Behavior and accessibility
+
+- Put it in `componentSlot`, not `title`. A tooltip wraps its title in a paragraph, and a table inside a paragraph is invalid HTML that React reports as an error in the console.
+
+- The table asks for at least 224px and a tooltip stops at 250px, so there is almost no slack: long row labels wrap and push the table into a scrollbar. Keeping labels to a word or two matters more here than anywhere else. `width="wide"` on the tooltip buys room for a table that genuinely needs it.
+
+- A disabled section is drawn in the disabled text colour and nothing more: it is still read out in full, so the reason it is dimmed has to come from somewhere else, such as the `contentAlert` above it.
+
+- Everything in a tooltip disappears with the pointer, and a real table of numbers is often worth putting on the page instead.
+
+## 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                                                                                                                                         |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`              | `Array<{` `label?: string;` `dataRows: {` `label: string;` `value: string \| number;` `}[];` `disabled?: boolean;` `}>` | -         | The sections, drawn in order and separated by dividers. A section's `label` heads it, its `dataRows` fill it, and `disabled` greys the whole block. |
+| `itemAlign`         | `"left" \| "right"`                                                                                                     | `"right"` | Which side of its column each value sits on. Right lines numbers up with each other.                                                                |
+| `showSectionHeader` | `boolean`                                                                                                               | `true`    | Whether section labels are drawn. False hides all of them; the dividers between sections stay.                                                      |
+| `contentAlert`      | `string \| JSX.Element`                                                                                                 | -         | A note above the whole table, for a caveat about the numbers. Takes an element, so it can hold a link.                                              |

package/data/component-docs/index.json

@@ -0,0 +1,267 @@
+{
+  "Accordion": {
+    "file": "Accordion.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Accordion/__storybook__/docs/content.html"
+  },
+  "Autocomplete": {
+    "file": "Autocomplete.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Autocomplete/__storybook__/docs/content.html"
+  },
+  "Banner": {
+    "file": "Banner.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Banner/__storybook__/docs/content.html"
+  },
+  "Button": {
+    "file": "Button.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Button/__storybook__/docs/content.html"
+  },
+  "ButtonDropdown": {
+    "file": "ButtonDropdown.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/ButtonDropdown/__storybook__/docs/content.html"
+  },
+  "ButtonGroup": {
+    "file": "ButtonGroup.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/ButtonGroup/__storybook__/docs/content.html"
+  },
+  "ButtonToggle": {
+    "file": "ButtonToggle.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/ButtonToggle/__storybook__/docs/content.html"
+  },
+  "Callout": {
+    "file": "Callout.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Callout/__storybook__/docs/content.html"
+  },
+  "CellBasic": {
+    "file": "CellBasic.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/CellBasic/__storybook__/docs/content.html"
+  },
+  "CellComponent": {
+    "file": "CellComponent.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/CellComponent/__storybook__/docs/content.html"
+  },
+  "CellHeader": {
+    "file": "CellHeader.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/CellHeader/__storybook__/docs/content.html"
+  },
+  "ComplexFilter": {
+    "file": "ComplexFilter.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/ComplexFilter/__storybook__/docs/content.html"
+  },
+  "ContentCard": {
+    "file": "ContentCard.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/ContentCard/__storybook__/docs/content.html"
+  },
+  "Dialog": {
+    "file": "Dialog.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Dialog/__storybook__/docs/content.html"
+  },
+  "Dropdown": {
+    "file": "Dropdown.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Dropdown/__storybook__/docs/content.html"
+  },
+  "DropdownMenu": {
+    "file": "DropdownMenu.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/DropdownMenu/__storybook__/docs/content.html"
+  },
+  "HeatmapChart": {
+    "file": "HeatmapChart.md",
+    "package": "@czi-sds/data-viz",
+    "source": "packages/data-viz/src/core/HeatmapChart/__storybook__/docs/content.html"
+  },
+  "Hero": {
+    "file": "Hero.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Hero/__storybook__/docs/content.html"
+  },
+  "Icon": {
+    "file": "Icon.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Icon/__storybook__/docs/content.html"
+  },
+  "InputCheckbox": {
+    "file": "InputCheckbox.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/InputCheckbox/__storybook__/docs/content.html"
+  },
+  "InputDropdown": {
+    "file": "InputDropdown.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/InputDropdown/__storybook__/docs/content.html"
+  },
+  "InputRadio": {
+    "file": "InputRadio.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/InputRadio/__storybook__/docs/content.html"
+  },
+  "InputSearch": {
+    "file": "InputSearch.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/InputSearch/__storybook__/docs/content.html"
+  },
+  "InputSlider": {
+    "file": "InputSlider.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/InputSlider/__storybook__/docs/content.html"
+  },
+  "InputText": {
+    "file": "InputText.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/InputText/__storybook__/docs/content.html"
+  },
+  "InputToggle": {
+    "file": "InputToggle.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/InputToggle/__storybook__/docs/content.html"
+  },
+  "IntentMessage": {
+    "file": "IntentMessage.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/IntentMessage/__storybook__/docs/content.html"
+  },
+  "Legend": {
+    "file": "Legend.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Legend/__storybook__/docs/content.html"
+  },
+  "Link": {
+    "file": "Link.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Link/__storybook__/docs/content.html"
+  },
+  "List": {
+    "file": "List.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/List/__storybook__/docs/content.html"
+  },
+  "LoadingIndicator": {
+    "file": "LoadingIndicator.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/LoadingIndicator/__storybook__/docs/content.html"
+  },
+  "Menu": {
+    "file": "Menu.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Menu/__storybook__/docs/content.html"
+  },
+  "MenuItem": {
+    "file": "MenuItem.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/MenuItem/__storybook__/docs/content.html"
+  },
+  "NavigationFooter": {
+    "file": "NavigationFooter.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/NavigationFooter/__storybook__/docs/content.html"
+  },
+  "NavigationHeader": {
+    "file": "NavigationHeader.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/NavigationHeader/__storybook__/docs/content.html"
+  },
+  "NavigationJumpTo": {
+    "file": "NavigationJumpTo.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/NavigationJumpTo/__storybook__/docs/content.html"
+  },
+  "Notification": {
+    "file": "Notification.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Notification/__storybook__/docs/content.html"
+  },
+  "Pagination": {
+    "file": "Pagination.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Pagination/__storybook__/docs/content.html"
+  },
+  "Panel": {
+    "file": "Panel.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Panel/__storybook__/docs/content.html"
+  },
+  "Popover": {
+    "file": "Popover.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Popover/__storybook__/docs/content.html"
+  },
+  "PreComposedTable": {
+    "file": "PreComposedTable.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/PreComposedTable/__storybook__/docs/content.html"
+  },
+  "ProteinStructureViewer": {
+    "file": "ProteinStructureViewer.md",
+    "package": "@czi-sds/data-viz",
+    "source": "packages/data-viz/src/core/ProteinStructureViewer/__storybook__/docs/content.html"
+  },
+  "SegmentedControl": {
+    "file": "SegmentedControl.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/SegmentedControl/__storybook__/docs/content.html"
+  },
+  "StackedBarChart": {
+    "file": "StackedBarChart.md",
+    "package": "@czi-sds/data-viz",
+    "source": "packages/data-viz/src/core/StackedBarChart/__storybook__/docs/content.html"
+  },
+  "Table": {
+    "file": "Table.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Table/__storybook__/docs/content.html"
+  },
+  "TableHeader": {
+    "file": "TableHeader.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/TableHeader/__storybook__/docs/content.html"
+  },
+  "TableRow": {
+    "file": "TableRow.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/TableRow/__storybook__/docs/content.html"
+  },
+  "Tabs": {
+    "file": "Tabs.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Tabs/__storybook__/docs/content.html"
+  },
+  "Tag": {
+    "file": "Tag.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Tag/__storybook__/docs/content.html"
+  },
+  "TagFilter": {
+    "file": "TagFilter.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/TagFilter/__storybook__/docs/content.html"
+  },
+  "Tooltip": {
+    "file": "Tooltip.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/Tooltip/__storybook__/docs/content.html"
+  },
+  "TooltipCondensed": {
+    "file": "TooltipCondensed.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/TooltipCondensed/__storybook__/docs/content.html"
+  },
+  "TooltipTable": {
+    "file": "TooltipTable.md",
+    "package": "@czi-sds/components",
+    "source": "packages/components/src/core/TooltipTable/__storybook__/docs/content.html"
+  }
+}

package/data/component-list.json

@@ -58,8 +58,5 @@
     "TooltipCondensed",
     "TooltipTable"
   ],
-  "data-viz": [
-    "HeatmapChart",
-    "StackedBarChart"
-  ]
-}
+  "data-viz": ["HeatmapChart", "ProteinStructureViewer", "StackedBarChart"]
+}