✨ 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.tsxindex 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.tsxindex 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 "json" and "options" 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>"light" | "dark"</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>"RIGHT" | "DOWN" | "LEFT" | "UP"</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>"light" | "dark"</Code>+ </Table.Td>+ <Table.Td>+ <Code>"dark"</Code>+ </Table.Td>+ </Table.Tr>+ <Table.Tr>+ <Table.Td>+ <Code>layoutDirection</Code>+ </Table.Td>+ <Table.Td>+ <Code>"RIGHT" | "DOWN" | "LEFT" | "UP"</Code>+ </Table.Td>+ <Table.Td>+ <Code>"RIGHT"</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) => void</Code>+ </Table.Td>+ <Table.Td>—</Table.Td>+ </Table.Tr>+ <Table.Tr>+ <Table.Td>+ <Code>onParse</Code>+ </Table.Td>+ <Table.Td>+ <Code>(graph: GraphData) => void</Code>+ </Table.Td>+ <Table.Td>—</Table.Td>+ </Table.Tr>+ <Table.Tr>+ <Table.Td>+ <Code>onParseError</Code>+ </Table.Td>+ <Table.Td>+ <Code>(error: Error) => 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>);};