",
"name": "dir",
- "required": false,
- "warnings": []
+ "required": false
},
"style": {
- "description": "Optional CSS properties.\nThe grid of cells will fill the height and width defined by this style.",
- "html": "
Optional CSS properties.\nThe grid of cells will fill the height and width defined by this style.
\n"
+ }
+ ],
+ "html": "
style?:CSSProperties
",
"name": "style",
- "required": false,
- "warnings": []
+ "required": false
},
"children": {
- "description": "Additional content to be rendered within the grid (above cells).\nThis property can be used to render things like overlays or tooltips.",
+ "description": [
+ {
+ "content": "
Additional content to be rendered within the grid (above cells).\nThis property can be used to render things like overlays or tooltips.
",
"name": "cellComponent",
- "required": true,
- "warnings": []
+ "required": true
},
"cellProps": {
- "description": "Additional props to be passed to the cell-rendering component.\nGrid will automatically re-render cells when values in this object change.",
+ "description": [
+ {
+ "content": "
Additional props to be passed to the cell-rendering component.\nGrid will automatically re-render cells when values in this object change.
\n"
+ },
+ {
+ "content": "
This object must not contain ariaAttributes, columnIndex, rowIndex, or style props.
\n",
+ "intent": "warning"
+ }
+ ],
"html": "
cellProps:CellProps
",
- "infos": [],
"name": "cellProps",
- "required": true,
- "warnings": [
- "This object must not contain ariaAttributes, columnIndex, rowIndex, or style props."
- ]
+ "required": true
},
"columnCount": {
- "description": "Number of columns to be rendered in the grid.",
+ "description": [
+ {
+ "content": "
Number of columns to be rendered in the grid.
\n"
+ }
+ ],
"html": "
columnCount:number
",
- "infos": [],
"name": "columnCount",
- "required": true,
- "warnings": []
+ "required": true
},
"columnWidth": {
- "description": "Column width; the following formats are supported: • number of pixels (number) • percentage of the grid's current width (string) • function that returns the row width (in pixels) given an index and cellProps",
+ "description": [
+ {
+ "content": "
Column width; the following formats are supported:
\n
\n
number of pixels (number)
\n
percentage of the grid's current width (string)
\n
function that returns the row width (in pixels) given an index and cellProps
Default height of grid for initial render.\nThis value is important for server rendering.
\n"
+ }
+ ],
+ "html": "
defaultHeight?:number=0
",
"name": "defaultHeight",
- "required": false,
- "warnings": []
+ "required": false
},
"defaultWidth": {
- "description": "Default width of grid for initial render.\nThis value is important for server rendering.",
- "html": "
",
- "infos": [
- "The useGridRef and useGridCallbackRef hooks are exported for convenience use in TypeScript projects."
+ "description": [
+ {
+ "content": "
Imperative Grid API.
\n"
+ },
+ {
+ "content": "
The useGridRef and useGridCallbackRef hooks are exported for convenience use in TypeScript projects.
",
"name": "onCellsRendered",
- "required": false,
- "warnings": []
+ "required": false
},
"onResize": {
- "description": "Callback notified when the Grid's outermost HTMLElement resizes.\nThis may be used to (re)scroll a cell into view.",
- "html": "
",
"name": "onResize",
- "required": false,
- "warnings": []
+ "required": false
},
"overscanCount": {
- "description": "How many additional rows/columns to render outside of the visible area.\nThis can reduce visual flickering near the edges of a grid when scrolling.",
- "html": "
How many additional rows/columns to render outside of the visible area.\nThis can reduce visual flickering near the edges of a grid when scrolling.
\n"
+ }
+ ],
+ "html": "
overscanCount?:number=3
",
"name": "overscanCount",
- "required": false,
- "warnings": []
+ "required": false
},
"rowCount": {
- "description": "Number of rows to be rendered in the grid.",
+ "description": [
+ {
+ "content": "
Number of rows to be rendered in the grid.
\n"
+ }
+ ],
"html": "
rowCount:number
",
- "infos": [],
"name": "rowCount",
- "required": true,
- "warnings": []
+ "required": true
},
"rowHeight": {
- "description": "Row height; the following formats are supported: • number of pixels (number) • percentage of the grid's current height (string) • function that returns the row height (in pixels) given an index and cellProps",
+ "description": [
+ {
+ "content": "
Row height; the following formats are supported:
\n
\n
number of pixels (number)
\n
percentage of the grid's current height (string)
\n
function that returns the row height (in pixels) given an index and cellProps
",
- "infos": [],
"name": "rowHeight",
- "required": true,
- "warnings": []
+ "required": true
},
"tagName": {
- "description": "Can be used to override the root HTML element rendered by the List component.\nThe default value is \"div\", meaning that List renders an HTMLDivElement as its root.",
- "html": "
Can be used to override the root HTML element rendered by the List component.\nThe default value is "div", meaning that List renders an HTMLDivElement as its root.
\n"
+ },
+ {
+ "content": "
In most use cases the default ARIA roles are sufficient and this prop is not needed.
",
"name": "tagName",
- "required": false,
- "warnings": [
- "In most use cases the default ARIA roles are sufficient and this prop is not needed."
- ]
+ "required": false
}
}
}
\ No newline at end of file
diff --git a/public/generated/js-docs/GridImperativeAPI.json b/public/generated/js-docs/GridImperativeAPI.json
new file mode 100644
index 00000000..a199d027
--- /dev/null
+++ b/public/generated/js-docs/GridImperativeAPI.json
@@ -0,0 +1,42 @@
+{
+ "description": [
+ {
+ "content": "
Ref used to interact with this component's imperative API.\nThis API has imperative methods for scrolling and a getter for the outermost DOM element.
\n"
+ },
+ {
+ "content": "
The useGridRef and useGridCallbackRef hooks are exported for convenience use in TypeScript projects.
",
"name": "className",
- "required": false,
- "warnings": []
+ "required": false
},
"style": {
- "description": "Optional CSS properties.\nThe list of rows will fill the height defined by this style.",
- "html": "
Optional CSS properties.\nThe list of rows will fill the height defined by this style.
\n"
+ }
+ ],
+ "html": "
style?:CSSProperties
",
"name": "style",
- "required": false,
- "warnings": []
+ "required": false
},
"children": {
- "description": "Additional content to be rendered within the list (above cells).\nThis property can be used to render things like overlays or tooltips.",
+ "description": [
+ {
+ "content": "
Additional content to be rendered within the list (above cells).\nThis property can be used to render things like overlays or tooltips.
\n"
+ }
+ ],
"html": "
children?:ReactNode
",
- "infos": [],
"name": "children",
- "required": false,
- "warnings": []
+ "required": false
},
"defaultHeight": {
- "description": "Default height of list for initial render.\nThis value is important for server rendering.",
- "html": "
",
- "infos": [
- "The useListRef and useListCallbackRef hooks are exported for convenience use in TypeScript projects."
+ "description": [
+ {
+ "content": "
Ref used to interact with this component's imperative API.
\n"
+ },
+ {
+ "content": "
This API has imperative methods for scrolling and a getter for the outermost DOM element.
\n"
+ },
+ {
+ "content": "
The useListRef and useListCallbackRef hooks are exported for convenience use in TypeScript projects.
",
"name": "listRef",
- "required": false,
- "warnings": []
+ "required": false
},
"onResize": {
- "description": "Callback notified when the List's outermost HTMLElement resizes.\nThis may be used to (re)scroll a row into view.",
- "html": "
",
"name": "onRowsRendered",
- "required": false,
- "warnings": []
+ "required": false
},
"overscanCount": {
- "description": "How many additional rows to render outside of the visible area.\nThis can reduce visual flickering near the edges of a list when scrolling.",
- "html": "
",
"name": "rowComponent",
- "required": true,
- "warnings": []
+ "required": true
},
"rowCount": {
- "description": "Number of items to be rendered in the list.",
+ "description": [
+ {
+ "content": "
Number of items to be rendered in the list.
\n"
+ }
+ ],
"html": "
rowCount:number
",
- "infos": [],
"name": "rowCount",
- "required": true,
- "warnings": []
+ "required": true
},
"rowHeight": {
- "description": "Row height; the following formats are supported: • number of pixels (number) • percentage of the grid's current height (string) • function that returns the row height (in pixels) given an index and cellProps • dynamic row height cache returned by the useDynamicRowHeight hook",
+ "description": [
+ {
+ "content": "
Row height; the following formats are supported:
\n
\n
number of pixels (number)
\n
percentage of the grid's current height (string)
\n
function that returns the row height (in pixels) given an index and cellProps
\n
dynamic row height cache returned by the useDynamicRowHeight hook
\n
\n"
+ },
+ {
+ "content": "
Dynamic row heights are not as efficient as predetermined sizes.\nIt's recommended to provide your own height values if they can be determined ahead of time.
",
- "infos": [],
"name": "rowHeight",
- "required": true,
- "warnings": [
- "Dynamic row heights are not as efficient as predetermined sizes.\nIt's recommended to provide your own height values if they can be determined ahead of time."
- ]
+ "required": true
},
"rowProps": {
- "description": "Additional props to be passed to the row-rendering component.\nList will automatically re-render rows when values in this object change.",
+ "description": [
+ {
+ "content": "
Additional props to be passed to the row-rendering component.\nList will automatically re-render rows when values in this object change.
\n"
+ },
+ {
+ "content": "
This object must not contain ariaAttributes, index, or style props.
\n",
+ "intent": "warning"
+ }
+ ],
"html": "
rowProps:RowProps
",
- "infos": [],
"name": "rowProps",
- "required": true,
- "warnings": [
- "This object must not contain ariaAttributes, index, or style props."
- ]
+ "required": true
},
"tagName": {
- "description": "Can be used to override the root HTML element rendered by the List component.\nThe default value is \"div\", meaning that List renders an HTMLDivElement as its root.",
- "html": "
Can be used to override the root HTML element rendered by the List component.\nThe default value is "div", meaning that List renders an HTMLDivElement as its root.
\n"
+ },
+ {
+ "content": "
In most use cases the default ARIA roles are sufficient and this prop is not needed.
",
"name": "tagName",
- "required": false,
- "warnings": [
- "In most use cases the default ARIA roles are sufficient and this prop is not needed."
- ]
+ "required": false
}
}
}
\ No newline at end of file
diff --git a/public/generated/js-docs/ListImperativeAPI.json b/public/generated/js-docs/ListImperativeAPI.json
new file mode 100644
index 00000000..8be088ee
--- /dev/null
+++ b/public/generated/js-docs/ListImperativeAPI.json
@@ -0,0 +1,24 @@
+{
+ "description": [
+ {
+ "content": "
Imperative List API.
\n"
+ },
+ {
+ "content": "
The useListRef and useListCallbackRef hooks are exported for convenience use in TypeScript projects.
+ And the usePanelCallbackRef hook returns a{" "}
+
+ ref callback function
+
+ . This is better when sharing the ref with another hook or component.
+
+
+
+ );
+}
diff --git a/src/routes/grid/PropsRoute.tsx b/src/routes/grid/PropsRoute.tsx
index 43d0f6f9..f011b8f4 100644
--- a/src/routes/grid/PropsRoute.tsx
+++ b/src/routes/grid/PropsRoute.tsx
@@ -1,11 +1,12 @@
import json from "../../../public/generated/js-docs/Grid.json";
import { Box } from "../../components/Box";
import { ComponentProps } from "../../components/props/ComponentProps";
+import type { ComponentMetadata } from "../../types";
export default function GridPropsRoute() {
return (
-
+
);
}
diff --git a/src/routes/grid/RenderingGridRoute.tsx b/src/routes/grid/RenderingGridRoute.tsx
index 61bad959..00763aa1 100644
--- a/src/routes/grid/RenderingGridRoute.tsx
+++ b/src/routes/grid/RenderingGridRoute.tsx
@@ -60,7 +60,7 @@ export default function RenderingGridRoute() {
-
+
);
}
diff --git a/src/routes/grid/ImperativeApiRoute.tsx b/src/routes/grid/ScrollToCellRoute.tsx
similarity index 99%
rename from src/routes/grid/ImperativeApiRoute.tsx
rename to src/routes/grid/ScrollToCellRoute.tsx
index af027136..874f70f8 100644
--- a/src/routes/grid/ImperativeApiRoute.tsx
+++ b/src/routes/grid/ScrollToCellRoute.tsx
@@ -45,7 +45,7 @@ const COLUMNS: Option[] = COLUMN_KEYS.map((key) => ({
value: key
})).sort((a, b) => a.label.localeCompare(b.label));
-export default function GridImperativeApiRoute() {
+export default function ScrollToCellRoute() {
const contacts = useContacts();
const titleOptions = useMemo[]>(() => {
diff --git a/src/routes/list/DynamicRowHeightsRoute.tsx b/src/routes/list/DynamicRowHeightsRoute.tsx
index e97c2213..be49157f 100644
--- a/src/routes/list/DynamicRowHeightsRoute.tsx
+++ b/src/routes/list/DynamicRowHeightsRoute.tsx
@@ -43,7 +43,7 @@ export default function DynamicRowHeightsRoute() {
recommended to provide your own height values if they can be determined
ahead of time.
-
+
);
}
diff --git a/src/routes/list/ImperativeApiRoute.tsx b/src/routes/list/ImperativeApiRoute.tsx
index 3be82bea..4d8eac2b 100644
--- a/src/routes/list/ImperativeApiRoute.tsx
+++ b/src/routes/list/ImperativeApiRoute.tsx
@@ -1,138 +1,36 @@
-import { useMemo, useState } from "react";
-import { List, useListRef, type Align } from "react-window";
-import listRefClickEventHandlerMarkdown from "../../../public/generated/code-snippets/listRefClickEventHandler.json";
-import useListCallbackRefMarkdown from "../../../public/generated/code-snippets/useListCallbackRef.json";
-import useListRefMarkdown from "../../../public/generated/code-snippets/useListRef.json";
-import useListRefImportMarkdown from "../../../public/generated/code-snippets/useListRefImport.json";
-import { Block } from "../../components/Block";
+import json from "../../../public/generated/js-docs/ListImperativeAPI.json";
import { Box } from "../../components/Box";
-import { Button } from "../../components/Button";
-import { Callout } from "../../components/Callout";
import { Code } from "../../components/code/Code";
-import { Header } from "../../components/Header";
-import { LoadingSpinner } from "../../components/LoadingSpinner";
-import { Select, type Option } from "../../components/Select";
-import { RowComponent } from "./examples/ListVariableRowHeights.example";
-import { rowHeight } from "./examples/rowHeight.example";
-import { useCitiesByState } from "./hooks/useCitiesByState";
-import { ContinueLink } from "../../components/ContinueLink";
-
-const EMPTY_OPTION: Option = {
- label: "",
- value: ""
-};
-
-const ALIGNMENTS: Option[] = (
- ["auto", "center", "end", "smart", "start"] satisfies Align[]
-).map((value) => ({
- label: `align: ${value}`,
- value
-}));
-ALIGNMENTS.unshift(EMPTY_OPTION as Option);
-
-const BEHAVIORS: Option[] = (
- ["auto", "instant", "smooth"] satisfies ScrollBehavior[]
-).map((value) => ({
- label: `behavior: ${value}`,
- value
-}));
-BEHAVIORS.unshift(EMPTY_OPTION as Option);
+import { ImperativeHandle } from "../../components/handles/ImperativeHandle";
+import type { ImperativeHandleMetadata } from "../../types";
+import { html as usePanelRefHTML } from "../../../public/generated/code-snippets/useListRef.json";
+import { html as usePanelCallbackRefHTML } from "../../../public/generated/code-snippets/useListCallbackRef.json";
+import { ExternalLink } from "../../components/ExternalLink";
export default function ListImperativeApiRoute() {
- const [align, setAlign] = useState | undefined>();
- const [behavior, setBehavior] = useState<
- Option | undefined
- >();
- const [state, setState] = useState>(EMPTY_OPTION);
-
- const citiesByState = useCitiesByState();
-
- const stateOptions = useMemo[]>(() => {
- const options: Option[] = citiesByState
- .filter((item) => item.type === "state")
- .map((item) => ({
- label: item.state,
- value: item.state
- }));
- options.unshift(EMPTY_OPTION);
-
- return options;
- }, [citiesByState]);
-
- const listRef = useListRef(null);
-
- const scrollToRow = () => {
- const index = citiesByState.findIndex(
- (item) => item.type === "state" && item.state === state.value
- );
- listRef.current?.scrollToRow({
- align: align?.value,
- behavior: behavior?.value,
- index
- });
- };
-
return (
-
+
+
- List provides an imperative API for responding to events. The
- recommended way to access this API is to use the exported ref hook:
+ And the usePanelCallbackRef hook returns a{" "}
+
+ ref callback function
+
+ . This is better when sharing the ref with another hook or component.
-
-
Attach the ref during render:
-
-
And call API methods in an event handler:
-
-
The form below uses the imperative API to scroll the list:
-
-
-
-
-
-
-
-
-
- {!citiesByState.length && }
-
-
-
- Note If you are passing the
- ref to another component or hook, use the ref callback function instead.
-
-
-
+
);
}
diff --git a/src/routes/list/PropsRoute.tsx b/src/routes/list/PropsRoute.tsx
index 273bb632..bac82a3e 100644
--- a/src/routes/list/PropsRoute.tsx
+++ b/src/routes/list/PropsRoute.tsx
@@ -1,11 +1,12 @@
import json from "../../../public/generated/js-docs/List.json";
import { Box } from "../../components/Box";
import { ComponentProps } from "../../components/props/ComponentProps";
+import type { ComponentMetadata } from "../../types";
export default function ListPropsRoute() {
return (
-
+
);
}
diff --git a/src/routes/list/ScrollToRowRoute.tsx b/src/routes/list/ScrollToRowRoute.tsx
new file mode 100644
index 00000000..9b157ce7
--- /dev/null
+++ b/src/routes/list/ScrollToRowRoute.tsx
@@ -0,0 +1,138 @@
+import { useMemo, useState } from "react";
+import { List, useListRef, type Align } from "react-window";
+import listRefClickEventHandlerMarkdown from "../../../public/generated/code-snippets/listRefClickEventHandler.json";
+import useListCallbackRefMarkdown from "../../../public/generated/code-snippets/useListCallbackRef.json";
+import useListRefMarkdown from "../../../public/generated/code-snippets/useListRef.json";
+import useListRefImportMarkdown from "../../../public/generated/code-snippets/useListRefImport.json";
+import { Block } from "../../components/Block";
+import { Box } from "../../components/Box";
+import { Button } from "../../components/Button";
+import { Callout } from "../../components/Callout";
+import { Code } from "../../components/code/Code";
+import { Header } from "../../components/Header";
+import { LoadingSpinner } from "../../components/LoadingSpinner";
+import { Select, type Option } from "../../components/Select";
+import { RowComponent } from "./examples/ListVariableRowHeights.example";
+import { rowHeight } from "./examples/rowHeight.example";
+import { useCitiesByState } from "./hooks/useCitiesByState";
+import { ContinueLink } from "../../components/ContinueLink";
+
+const EMPTY_OPTION: Option = {
+ label: "",
+ value: ""
+};
+
+const ALIGNMENTS: Option[] = (
+ ["auto", "center", "end", "smart", "start"] satisfies Align[]
+).map((value) => ({
+ label: `align: ${value}`,
+ value
+}));
+ALIGNMENTS.unshift(EMPTY_OPTION as Option);
+
+const BEHAVIORS: Option[] = (
+ ["auto", "instant", "smooth"] satisfies ScrollBehavior[]
+).map((value) => ({
+ label: `behavior: ${value}`,
+ value
+}));
+BEHAVIORS.unshift(EMPTY_OPTION as Option);
+
+export default function ScrollToRowRoute() {
+ const [align, setAlign] = useState | undefined>();
+ const [behavior, setBehavior] = useState<
+ Option | undefined
+ >();
+ const [state, setState] = useState>(EMPTY_OPTION);
+
+ const citiesByState = useCitiesByState();
+
+ const stateOptions = useMemo[]>(() => {
+ const options: Option[] = citiesByState
+ .filter((item) => item.type === "state")
+ .map((item) => ({
+ label: item.state,
+ value: item.state
+ }));
+ options.unshift(EMPTY_OPTION);
+
+ return options;
+ }, [citiesByState]);
+
+ const listRef = useListRef(null);
+
+ const scrollToRow = () => {
+ const index = citiesByState.findIndex(
+ (item) => item.type === "state" && item.state === state.value
+ );
+ listRef.current?.scrollToRow({
+ align: align?.value,
+ behavior: behavior?.value,
+ index
+ });
+ };
+
+ return (
+
+
+
+ List provides an imperative API for responding to events. The
+ recommended way to access this API is to use the exported ref hook:
+
+
+
Attach the ref during render:
+
+
And call API methods in an event handler:
+
+
The form below uses the imperative API to scroll the list: