Merge pull request #2910 from finos/fix-api-docs

Fix API docs
finos · Feb 4, 2025 · 69f2fdd · 69f2fdd
2 parents 3ccef43 + 415285a
commit 69f2fdd
Show file tree

Hide file tree

Showing 13 changed files with 81 additions and 25 deletions.
diff --git a/docs/md/SUMMARY.md b/docs/md/SUMMARY.md
@@ -42,6 +42,7 @@
         -   [Hosting a `WebSocketServer` in Node.js](./how_to/javascript/nodejs_server.md)
     -   [`perspective-viewer` Custom Element library](./how_to/javascript/viewer.md)
         -   [Theming](./how_to/javascript/theming.md)
+        -   [Custom Themes](./how_to/javascript/custom_themes.md)
         -   [Loading data from a `Table`](./how_to/javascript/loading_data.md)
         -   [Loading data from a virtual `Table`](./how_to/javascript/loading_virtual_data.md)
         -   [Saving and restoring UI state](./how_to/javascript/save_restore.md)

diff --git a/docs/md/how_to/javascript/custom_themes.md b/docs/md/how_to/javascript/custom_themes.md
@@ -0,0 +1,28 @@
+# Custom themes
+
+The best way to write a new theme is to
+[fork and modify an existing theme](https://github.com/finos/perspective/tree/master/rust/perspective-viewer/src/themes),
+which are _just_ collections of regular CSS variables (no preprocessor is
+required, though Perspective's own themes use one). `<perspective-viewer>` is
+not "themed" by default and will lack icons and label text in addition to colors
+and fonts, so starting from an empty theme forces you to define _every_
+theme-able variable to get a functional UI.
+
+### Icons and Translation
+
+UI icons are defined by CSS variables provided by
+[`@finos/perspective-viewer/dist/css/icons.css`](https://github.com/finos/perspective/blob/master/rust/perspective-viewer/src/themes/icons.less).
+These variables must be defined for the UI icons to work - there are no default
+icons without a theme.
+
+UI text is also defined in CSS variables provided by
+[`@finos/perspective-viewer/dist/css/intl.css`](https://github.com/finos/perspective/blob/master/rust/perspective-viewer/src/themes/intl.less),
+and has identical import requirements. Some _example definitions_
+(automatically-translated sans-editing) can be found
+[`@finos/perspective-viewer/dist/css/intl/` folder](https://github.com/finos/perspective/tree/master/rust/perspective-viewer/src/themes/intl).
+
+Importing the pre-built `themes.css` stylesheet as well as a custom theme will
+define Icons and Translation globally as a side-effect. You can still customize
+icons in this mode with rules (of the appropriate specificity), _but_ if you do
+not still remember to define these variables yourself, your theme will not work
+without the base `themes.css` pacage available.
diff --git a/examples/blocks/src/editable/index.html b/examples/blocks/src/editable/index.html
@@ -2,24 +2,26 @@
 <html>
     <head>
         <meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,minimum-scale=1,user-scalable=no" />
-        <link rel="preload" href="/node_modules/@finos/perspective/dist/wasm/perspective-server.wasm" as="fetch" type="application/wasm" crossorigin="anonymous" />
-        <link rel="preload" href="/node_modules/@finos/perspective-viewer/dist/wasm/perspective-viewer.wasm" as="fetch" type="application/wasm" crossorigin="anonymous" />
-        <link rel="preload" href="/node_modules/superstore-arrow/superstore.lz4.arrow" as="fetch" type="arraybuffer" crossorigin="anonymous" />
-        <link rel="stylesheet" crossorigin="anonymous" href="/node_modules/@finos/perspective-viewer/dist/css/themes.css" />
+        <link rel="preload" href="https://cdn.jsdelivr.net/npm/@finos/perspective/dist/cdn/perspective-server.wasm" as="fetch" type="application/wasm" crossorigin="anonymous" />
+        <link rel="preload" href="https://cdn.jsdelivr.net/npm/@finos/perspective-viewer/dist/cdn/perspective-viewer.wasm" as="fetch" type="application/wasm" crossorigin="anonymous" />
+        <link rel="preload" href="https://cdn.jsdelivr.net/npm/superstore-arrow/superstore.lz4.arrow" as="fetch" type="arraybuffer" crossorigin="anonymous" />
+        <!-- <link rel="stylesheet" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@finos/perspective-viewer/dist/css/themes.css" /> -->
+        <link rel="stylesheet" href="customStyle.css" />
         <script type="module">
-            import "/node_modules/@finos/perspective-viewer/dist/cdn/perspective-viewer.js";
-            import "/node_modules/@finos/perspective-viewer-datagrid/dist/cdn/perspective-viewer-datagrid.js";
-            import "/node_modules/@finos/perspective-viewer-d3fc/dist/cdn/perspective-viewer-d3fc.js";
+            import "https://cdn.jsdelivr.net/npm/@finos/perspective-viewer@3.3.2/dist/cdn/perspective-viewer.js";
+            import "https://cdn.jsdelivr.net/npm/@finos/perspective-viewer-datagrid@3.3.2/dist/cdn/perspective-viewer-datagrid.js";
+            import "https://cdn.jsdelivr.net/npm/@finos/perspective-viewer-d3fc@3.3.2/dist/cdn/perspective-viewer-d3fc.js";
 
-            import perspective from "/node_modules/@finos/perspective/dist/cdn/perspective.js";
+            import perspective from "https://cdn.jsdelivr.net/npm/@finos/perspective@3.3.2/dist/cdn/perspective.js";
 
             const worker = await perspective.worker();
-            const resp = await fetch("/node_modules/superstore-arrow/superstore.lz4.arrow");
+            const resp = await fetch("https://cdn.jsdelivr.net/npm/superstore-arrow/superstore.lz4.arrow");
             const arrow = await resp.arrayBuffer();
             const viewer = document.getElementsByTagName("perspective-viewer")[0];
             const table = worker.table(arrow);
             viewer.load(table);
-            viewer.restore({ settings: true, plugin_config: { edit_mode: "EDIT" } });
+            viewer.restore({ settings: true });
+            viewer.resetThemes(["Style1", "Pro Dark", "Pro Light"]);
         </script>
         <style>
             perspective-viewer {

diff --git a/examples/react-example/package.json b/examples/react-example/package.json
@@ -20,6 +20,8 @@
     },
     "devDependencies": {
         "esbuild": "^0.14.54",
-        "http-server": "^14.1.1"
+        "http-server": "^14.1.1",
+        "@types/react": "^18",
+        "@types/react-dom": "^18"
     }
 }
diff --git a/examples/react-example/src/index.tsx b/examples/react-example/src/index.tsx
@@ -17,7 +17,10 @@ import perspective from "@finos/perspective";
 import perspective_viewer from "@finos/perspective-viewer";
 import "@finos/perspective-viewer-datagrid";
 import "@finos/perspective-viewer-d3fc";
-import type { ViewerConfigUpdate } from "@finos/perspective-viewer";
+import type {
+    HTMLPerspectiveViewerElement,
+    ViewerConfigUpdate,
+} from "@finos/perspective-viewer";
 
 import "@finos/perspective-viewer/dist/css/themes.css";
 import "./index.css";
@@ -50,7 +53,7 @@ const config: ViewerConfigUpdate = {
 };
 
 const App = (): React.ReactElement => {
-    const viewer = React.useRef(null);
+    const viewer = React.useRef<HTMLPerspectiveViewerElement>(null);
     React.useEffect(() => {
         getTable().then((table) => {
             if (viewer.current) {
@@ -63,4 +66,6 @@ const App = (): React.ReactElement => {
     return <perspective-viewer ref={viewer}></perspective-viewer>;
 };
 
-ReactDOM.createRoot(document.getElementById("root")).render(<App />);
+ReactDOM.createRoot(
+    document.getElementById("root") as ReactDOM.Container
+).render(<App />);
diff --git a/examples/react-example/tsconfig.json b/examples/react-example/tsconfig.json
@@ -12,7 +12,7 @@
         "noImplicitUseStrict": false,
         "noUnusedLocals": true,
         "strictNullChecks": true,
-        "skipLibCheck": true,
+        "skipLibCheck": false,
         "removeComments": false,
         "jsx": "react",
         "allowSyntheticDefaultImports": true,

diff --git a/packages/perspective-viewer-d3fc/package.json b/packages/perspective-viewer-d3fc/package.json
@@ -7,7 +7,7 @@
     "type": "module",
     "exports": {
         ".": {
-            "types": "./dist/esm/types/index.d.ts",
+            "types": "./dist/esm/index.d.ts",
             "default": "./dist/esm/perspective-viewer-d3fc.js"
         },
         "./src/*": "./src/*",
@@ -31,7 +31,7 @@
         "src/**/*",
         "index.d.ts"
     ],
-    "types": "dist/esm/types/index.d.ts",
+    "types": "dist/esm/index.d.ts",
     "scripts": {
         "prebuild": "mkdirp dist/esm",
         "build": "node ./build.js",

diff --git a/packages/perspective-viewer-datagrid/package.json b/packages/perspective-viewer-datagrid/package.json
@@ -5,7 +5,10 @@
     "unpkg": "dist/cdn/perspective-viewer-datagrid.js",
     "jsdelivr": "dist/cdn/perspective-viewer-datagrid.js",
     "exports": {
-        ".": "./dist/esm/perspective-viewer-datagrid.js",
+        ".": {
+            "types": "./index.d.ts",
+            "default": "./dist/esm/perspective-viewer-datagrid.js"
+        },
         "./dist/*": "./dist/*",
         "./package.json": "./package.json"
     },
@@ -14,7 +17,6 @@
         "dist/**/*",
         "index.d.ts"
     ],
-    "types": "index.d.ts",
     "scripts": {
         "build": "node build.js",
         "clean": "rimraf dist",

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/rust/perspective-js/Cargo.toml b/rust/perspective-js/Cargo.toml
@@ -23,6 +23,7 @@ keywords = ["experimental"]
 include = ["src/**/*", "Cargo.toml", "./package.json", "docs/**/*", "build.rs"]
 
 [package.metadata.docs.rs]
+features = ["external-docs"]
 rustc-args = ["--cfg", "web_sys_unstable_apis"]
 rustdoc-args = ["--html-in-header", "docs/index.html"]
 

diff --git a/rust/perspective-python/Cargo.toml b/rust/perspective-python/Cargo.toml
@@ -39,6 +39,7 @@ include = [
 ]
 
 [package.metadata.docs.rs]
+features = ["external-docs"]
 rustdoc-args = ["--html-in-header", "docs/index.html"]
 
 [features]

diff --git a/rust/perspective-viewer/src/less/config-selector.less b/rust/perspective-viewer/src/less/config-selector.less
@@ -267,7 +267,7 @@
             top: 0px;
             margin: var(--column-drop-label--margin, -16px 0px 0px 0px);
             font-size: var(--label--font-size, 0.75em);
-            display: var(--column-drop-label--display, none);
+            display: inline-block;
         }
 
         #transpose_button {

diff --git a/rust/perspective-viewer/src/themes/pro.less b/rust/perspective-viewer/src/themes/pro.less
@@ -63,7 +63,6 @@ perspective-string-column-style[theme="Pro Light"] {
     --config-button--padding: 15px 8px 6px 8px;
     --column-drop-label--font-size: 8px;
     --column-drop-container--padding: 0px;
-    --column-drop-label--display: inline-block;
     --column-selector--width: 20px;
     --column-selector--font-size: 16px;