Skip to content

✨ Innovative and open-source visualization application that transforms various data formats, such as JSON, YAML, XML and CSV into interactive graphs.

feat: enhance documentation with additional examples and improved layout

AykutSarac776d29ebf901
diff --git a/apps/www/src/pages/_app.tsx b/apps/www/src/pages/_app.tsx
index 4333d97a..e283186c 100644
--- a/apps/www/src/pages/_app.tsx
+++ b/apps/www/src/pages/_app.tsx
@@ -19,7 +19,7 @@ import { smartColorSchemeManager } from "../lib/utils/mantineColorScheme";
async function loadShiki() {
const { createHighlighter } = await import("shiki");
const shiki = await createHighlighter({
- langs: ["typescript", "json", "go", "kotlin", "rust"],
+ langs: ["typescript", "json", "go", "kotlin", "rust", "html", "bash", "javascript"],
themes: [],
});
diff --git a/apps/www/src/pages/docs.tsx b/apps/www/src/pages/docs.tsx
index 68ee2aed..847e4283 100644
--- a/apps/www/src/pages/docs.tsx
+++ b/apps/www/src/pages/docs.tsx
@@ -1,6 +1,17 @@
import React from "react";
import Head from "next/head";
-import { Group, Paper, Stack, Text, Title } from "@mantine/core";
+import {
+ Anchor,
+ Badge,
+ Code,
+ Container,
+ Divider,
+ Paper,
+ Stack,
+ Table,
+ Text,
+ Title,
+} from "@mantine/core";
import { CodeHighlight } from "@mantine/code-highlight";
import styled from "styled-components";
import { generateNextSeo } from "next-seo/pages";
@@ -8,33 +19,79 @@ import { SEO } from "../constants/seo";
import Layout from "../layout/PageLayout";
const StyledFrame = styled.iframe`
- border: none;
- width: 80%;
- flex: 500px;
- margin: 3% auto;
+ border: 1px solid #e0e0e0;
+ border-radius: 12px;
+ width: 100%;
+ height: 420px;
`;
-const StyledContentBody = styled.div`
- display: flex;
- flex-direction: column;
- flex-wrap: wrap;
- gap: 15px;
- line-height: 1.8;
- overflow-x: auto;
-`;
+const iframeExample = `<iframe
+ id="json-crack-embed"
+ src="https://jsoncrack.com/widget"
+ width="100%"
+ height="600"
+ style="border: none;"
+></iframe>`;
-const StyledHighlight = styled.span<{ $link?: boolean; $alert?: boolean }>`
- display: inline-block;
- text-align: left;
- color: ${({ theme, $link, $alert }) =>
- $alert ? theme.DANGER : $link ? theme.BLURPLE : theme.TEXT_POSITIVE};
- background: ${({ theme }) => theme.BACKGROUND_TERTIARY};
- border-radius: 4px;
- font-weight: 500;
- padding: 2px 4px;
- font-size: 14px;
- margin: ${({ $alert }) => ($alert ? "8px 0" : "1px")};
-`;
+const fetchExample = `<iframe
+ id="json-crack-embed"
+ src="https://jsoncrack.com/widget?json=https://catfact.ninja/fact"
+ width="100%"
+ height="600"
+ style="border: none;"
+></iframe>`;
+
+const postMessageExample = `const iframe = document.getElementById("json-crack-embed");
+
+// Wait for the widget to signal it's ready
+window.addEventListener("message", (event) => {
+ if (event.data === "json-crack-embed") {
+ // Widget is ready — send data
+ iframe.contentWindow.postMessage({
+ json: JSON.stringify({ hello: "world" }),
+ options: {
+ theme: "light",
+ direction: "DOWN"
+ }
+ }, "*");
+ }
+});`;
+
+const reactInstall = `npm install jsoncrack-react`;
+
+const reactUsage = `import { JSONCrack } from "jsoncrack-react";
+import "jsoncrack-react/style.css";
+
+export default function App() {
+ return (
+ <div style={{ height: 600 }}>
+ <JSONCrack
+ json={{ name: "Ada", languages: ["Python", "Rust"] }}
+ theme="light"
+ layoutDirection="DOWN"
+ />
+ </div>
+ );
+}`;
+
+const reactRefExample = `import { useRef } from "react";
+import { JSONCrack, JSONCrackRef } from "jsoncrack-react";
+import "jsoncrack-react/style.css";
+
+export default function App() {
+ const ref = useRef<JSONCrackRef>(null);
+
+ return (
+ <>
+ <button onClick={() => ref.current?.centerView()}>
+ Center
+ </button>
+ <div style={{ height: 600 }}>
+ <JSONCrack ref={ref} json='{"a":1}' />
+ </div>
+ </>
+ );
+}`;
const Docs = () => {
return (
@@ -43,110 +100,401 @@ const Docs = () => {
{generateNextSeo({
...SEO,
title: "Documentation - JSON Crack",
- description: "Integrate JSON Crack widgets into your website.",
+ description:
+ "Integrate JSON Crack into your website with iframes, postMessage API, or the React component.",
canonical: "https://jsoncrack.com/docs",
})}
</Head>
- <Stack mx="auto" maw="90%">
- <Group mb="lg" mt={40}>
- <Title order={1} c="dark">
- Embed
- </Title>
- </Group>
- <Paper bg="white" c="black" p="md" radius="md" withBorder>
- <Title mb="sm" order={3} c="dark">
- # Fetching from URL
- </Title>
- <StyledContentBody>
- <Text>
- By adding <StyledHighlight>?json=https://catfact.ninja/fact</StyledHighlight> query at
- the end of iframe src you will be able to fetch from URL at widgets without additional
- scripts. This applies to editor page as well, the following link will fetch the url at
- the editor:{" "}
- <StyledHighlight
- as="a"
- href="https://jsoncrack.com/editor?json=https://catfact.ninja/fact"
- $link
- >
- https://jsoncrack.com/editor?json=https://catfact.ninja/fact
- </StyledHighlight>
- </Text>
-
- <StyledFrame
- title="Untitled"
- src="https://codepen.io/AykutSarac/embed/KKBpWVR?default-tab=html%2Cresult"
- loading="eager"
- >
- See the Pen <a href="https://codepen.io/AykutSarac/pen/KKBpWVR">Untitled</a> by Aykut
- Saraç (<a href="https://codepen.io/AykutSarac">@AykutSarac</a>) on{" "}
- <a href="https://codepen.io">CodePen</a>.
- </StyledFrame>
- </StyledContentBody>
- </Paper>
- <Paper bg="white" c="black" p="md" radius="md" withBorder>
- <Title mb="sm" order={3} c="dark">
- # Communicating with API
+ <Container size="md" py={60}>
+ <Stack gap={12} mb={48}>
+ <Title order={1} c="gray.9" fz={{ base: 28, sm: 36 }}>
+ Embed Documentation
</Title>
- <Title order={4}>◼︎ Post Message to Embed</Title>
- <StyledContentBody>
- <Text>
- Communicating with the embed is possible with{" "}
- <StyledHighlight
- as="a"
- href="https://developer.mozilla.org/en-US/docs/Web/API/MessagePort/postMessage"
- $link
+ <Text c="gray.6" fz={18} maw={600}>
+ Three ways to integrate JSON Crack into your app: iframe widget, postMessage API, or the
+ React component.
+ </Text>
+ </Stack>
+
+ <Stack gap={40}>
+ {/* Method 1: Basic iframe */}
+ <Paper bg="white" p={{ base: "md", sm: "xl" }} radius="lg" withBorder>
+ <Stack gap="md">
+ <Badge variant="light" color="blue" size="lg" radius="sm" w="fit-content">
+ 1. Iframe Widget
+ </Badge>
+ <Text c="gray.7" fz={15} lh={1.7}>
+ The simplest way to embed JSON Crack. Add an iframe pointing to{" "}
+ <Code>/widget</Code> and it will render an interactive graph viewer.
+ </Text>
+ <CodeHighlight
+ language="html"
+ code={iframeExample}
+ withCopyButton
+ styles={{ root: { borderRadius: 8 } }}
+ />
+ </Stack>
+ </Paper>
+
+ {/* Method 2: Fetch from URL */}
+ <Paper bg="white" p={{ base: "md", sm: "xl" }} radius="lg" withBorder>
+ <Stack gap="md">
+ <Badge variant="light" color="blue" size="lg" radius="sm" w="fit-content">
+ 2. Load Data from URL
+ </Badge>
+ <Text c="gray.7" fz={15} lh={1.7}>
+ Pass a <Code>json</Code> query parameter with a URL to automatically fetch and
+ display remote data. This works on both the widget and the{" "}
+ <Anchor href="/editor?json=https://catfact.ninja/fact" fz={15}>
+ editor
+ </Anchor>{" "}
+ page.
+ </Text>
+ <CodeHighlight
+ language="html"
+ code={fetchExample}
+ withCopyButton
+ styles={{ root: { borderRadius: 8 } }}
+ />
+ <StyledFrame
+ title="Fetch from URL example"
+ src="https://codepen.io/AykutSarac/embed/KKBpWVR?default-tab=html%2Cresult"
+ loading="eager"
+ />
+ </Stack>
+ </Paper>
+
+ {/* Method 3: postMessage API */}
+ <Paper bg="white" p={{ base: "md", sm: "xl" }} radius="lg" withBorder>
+ <Stack gap="md">
+ <Badge variant="light" color="blue" size="lg" radius="sm" w="fit-content">
+ 3. postMessage API
+ </Badge>
+ <Text c="gray.7" fz={15} lh={1.7}>
+ For dynamic updates, use the{" "}
+ <Anchor
+ href="https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage"
+ target="_blank"
+ fz={15}
+ >
+ postMessage API
+ </Anchor>{" "}
+ to send JSON data and display options to the widget at any time.
+ </Text>
+
+ <Paper
+ bg="yellow.0"
+ p="sm"
+ radius="md"
+ withBorder
+ bd="1px solid var(--mantine-color-yellow-3)"
>
- MessagePort
- </StyledHighlight>
- , you should pass an object consist of &quot;json&quot; and &quot;options&quot; key
- where json is a string and options is an object that may contain the following:
+ <Text c="gray.8" fz={14} lh={1.7}>
+ <Text span fw={600}>
+ Important:
+ </Text>{" "}
+ The iframe must be defined <b>before</b> the script tag. The widget posts its{" "}
+ <Code>id</Code> attribute back to the parent when ready — listen for this message
+ before sending data.
+ </Text>
+ </Paper>
+
<CodeHighlight
- w={500}
- language="json"
- code={
- '{\n theme: "light" | "dark",\n direction: "TOP" | "RIGHT" | "DOWN" | "LEFT"\n}'
- }
- withCopyButton={false}
+ language="javascript"
+ code={postMessageExample}
+ withCopyButton
+ styles={{ root: { borderRadius: 8 } }}
/>
- </Text>
-
- <StyledFrame
- scrolling="no"
- title="Untitled"
- src="https://codepen.io/AykutSarac/embed/rNrVyWP?default-tab=html%2Cresult"
- loading="lazy"
- >
- See the Pen <a href="https://codepen.io/AykutSarac/pen/rNrVyWP">Untitled</a> by Aykut
- Saraç (<a href="https://codepen.io/AykutSarac">@AykutSarac</a>) on{" "}
- <a href="https://codepen.io">CodePen</a>.
- </StyledFrame>
- </StyledContentBody>
- </Paper>
- <Paper bg="white" c="black" p="md" radius="md" withBorder>
- <Title order={4}>◼︎ On Page Load</Title>
- <StyledContentBody>
- <Text>
- <Text>
- ⚠️ <b>Important!</b> - iframe should be defined before the script tag
+
+ <Title order={4} c="gray.8" mt="xs">
+ Message Options
+ </Title>
+ <Table
+ withTableBorder
+ withColumnBorders
+ styles={{
+ table: { borderRadius: 8, overflow: "hidden" },
+ }}
+ >
+ <Table.Thead bg="gray.0">
+ <Table.Tr>
+ <Table.Th c="gray.7">Property</Table.Th>
+ <Table.Th c="gray.7">Type</Table.Th>
+ <Table.Th c="gray.7">Description</Table.Th>
+ </Table.Tr>
+ </Table.Thead>
+ <Table.Tbody>
+ <Table.Tr>
+ <Table.Td>
+ <Code>json</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>string</Code>
+ </Table.Td>
+ <Table.Td>Stringified JSON data to visualize</Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>options.theme</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>&quot;light&quot; | &quot;dark&quot;</Code>
+ </Table.Td>
+ <Table.Td>Color theme for the graph</Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>options.direction</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>&quot;RIGHT&quot; | &quot;DOWN&quot; | &quot;LEFT&quot; | &quot;UP&quot;</Code>
+ </Table.Td>
+ <Table.Td>
+ Layout direction of the graph (default: <Code>RIGHT</Code>)
+ </Table.Td>
+ </Table.Tr>
+ </Table.Tbody>
+ </Table>
+
+ <StyledFrame
+ title="Post message example"
+ src="https://codepen.io/AykutSarac/embed/rNrVyWP?default-tab=html%2Cresult"
+ loading="lazy"
+ />
+
+ <Divider my="xs" />
+
+ <Title order={4} c="gray.8">
+ Sending Data on Page Load
+ </Title>
+ <StyledFrame
+ title="On page load example"
+ src="https://codepen.io/AykutSarac/embed/QWBbpqx?default-tab=html%2Cresult"
+ loading="lazy"
+ />
+ </Stack>
+ </Paper>
+
+ {/* Method 4: React Component */}
+ <Paper bg="white" p={{ base: "md", sm: "xl" }} radius="lg" withBorder>
+ <Stack gap="md">
+ <Badge variant="light" color="violet" size="lg" radius="sm" w="fit-content">
+ React Component
+ </Badge>
+ <Text c="gray.7" fz={15} lh={1.7}>
+ For React applications, use the{" "}
+ <Anchor
+ href="https://www.npmjs.com/package/jsoncrack-react"
+ target="_blank"
+ fz={15}
+ >
+ jsoncrack-react
+ </Anchor>{" "}
+ package for a native integration with full control over props and callbacks.
</Text>
- <Text>
- ⚠️ <b>Note</b> - Widget is not loaded immediately with the parent page. The widget
- sends its <b>id</b> attribute so you can listen for it as in the example below to
- ensure its loaded and ready to listen for messages.
+
+ <CodeHighlight
+ language="bash"
+ code={reactInstall}
+ withCopyButton
+ styles={{ root: { borderRadius: 8 } }}
+ />
+ <CodeHighlight
+ language="typescript"
+ code={reactUsage}
+ withCopyButton
+ styles={{ root: { borderRadius: 8 } }}
+ />
+
+ <Paper
+ bg="blue.0"
+ p="sm"
+ radius="md"
+ withBorder
+ bd="1px solid var(--mantine-color-blue-2)"
+ >
+ <Text c="gray.8" fz={14} lh={1.7}>
+ The container element <b>must</b> have an explicit height. The component will fill
+ its parent.
+ </Text>
+ </Paper>
+
+ <Title order={4} c="gray.8" mt="xs">
+ Props
+ </Title>
+ <Table
+ withTableBorder
+ withColumnBorders
+ styles={{
+ table: { borderRadius: 8, overflow: "hidden" },
+ }}
+ >
+ <Table.Thead bg="gray.0">
+ <Table.Tr>
+ <Table.Th c="gray.7">Prop</Table.Th>
+ <Table.Th c="gray.7">Type</Table.Th>
+ <Table.Th c="gray.7">Default</Table.Th>
+ </Table.Tr>
+ </Table.Thead>
+ <Table.Tbody>
+ <Table.Tr>
+ <Table.Td>
+ <Code>json</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>string | object | unknown[]</Code>
+ </Table.Td>
+ <Table.Td>required</Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>theme</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>&quot;light&quot; | &quot;dark&quot;</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>&quot;dark&quot;</Code>
+ </Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>layoutDirection</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>&quot;RIGHT&quot; | &quot;DOWN&quot; | &quot;LEFT&quot; | &quot;UP&quot;</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>&quot;RIGHT&quot;</Code>
+ </Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>showControls</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>boolean</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>true</Code>
+ </Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>showGrid</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>boolean</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>true</Code>
+ </Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>maxRenderableNodes</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>number</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>1500</Code>
+ </Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>onNodeClick</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>(node: NodeData) =&gt; void</Code>
+ </Table.Td>
+ <Table.Td>—</Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>onParse</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>(graph: GraphData) =&gt; void</Code>
+ </Table.Td>
+ <Table.Td>—</Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>onParseError</Code>
+ </Table.Td>
+ <Table.Td>
+ <Code>(error: Error) =&gt; void</Code>
+ </Table.Td>
+ <Table.Td>—</Table.Td>
+ </Table.Tr>
+ </Table.Tbody>
+ </Table>
+
+ <Divider my="xs" />
+
+ <Title order={4} c="gray.8">
+ Ref Methods
+ </Title>
+ <Text c="gray.7" fz={15} lh={1.7}>
+ Use a ref to programmatically control the viewport:
</Text>
- </Text>
- <StyledFrame
- title="Untitled"
- src="https://codepen.io/AykutSarac/embed/QWBbpqx?default-tab=html%2Cresult"
- loading="lazy"
- >
- See the Pen <a href="https://codepen.io/AykutSarac/pen/QWBbpqx">Untitled</a> by Aykut
- Saraç (<a href="https://codepen.io/AykutSarac">@AykutSarac</a>) on{" "}
- <a href="https://codepen.io">CodePen</a>.
- </StyledFrame>
- </StyledContentBody>
- </Paper>
- </Stack>
+ <CodeHighlight
+ language="typescript"
+ code={reactRefExample}
+ withCopyButton
+ styles={{ root: { borderRadius: 8 } }}
+ />
+ <Table
+ withTableBorder
+ withColumnBorders
+ styles={{
+ table: { borderRadius: 8, overflow: "hidden" },
+ }}
+ >
+ <Table.Thead bg="gray.0">
+ <Table.Tr>
+ <Table.Th c="gray.7">Method</Table.Th>
+ <Table.Th c="gray.7">Description</Table.Th>
+ </Table.Tr>
+ </Table.Thead>
+ <Table.Tbody>
+ <Table.Tr>
+ <Table.Td>
+ <Code>zoomIn()</Code>
+ </Table.Td>
+ <Table.Td>Zoom in by 0.1</Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>zoomOut()</Code>
+ </Table.Td>
+ <Table.Td>Zoom out by 0.1</Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>setZoom(factor)</Code>
+ </Table.Td>
+ <Table.Td>Set zoom to a specific level</Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>centerView()</Code>
+ </Table.Td>
+ <Table.Td>Fit the entire graph into view</Table.Td>
+ </Table.Tr>
+ <Table.Tr>
+ <Table.Td>
+ <Code>focusFirstNode()</Code>
+ </Table.Td>
+ <Table.Td>Center on the root node</Table.Td>
+ </Table.Tr>
+ </Table.Tbody>
+ </Table>
+ </Stack>
+ </Paper>
+ </Stack>
+ </Container>
</Layout>
);
};