feat(website): revise environment doc

packages/react/src/providers/environment/examples/setup.tsx

@@ -0,0 +1,10 @@
+import Frame from 'react-frame-component'
+import { Environment } from '../'
+
+export const App = () => {
+  return (
+    <Frame title="IFrame Context">
+      <Environment>{/* Your App */}</Environment>
+    </Frame>
+  )
+}

packages/react/src/providers/environment/examples/usage.tsx

@@ -0,0 +1,7 @@
+import { useEnvironmentContext } from '../use-environment-context'
+
+export const Usage = () => {
+  const { getRootNode } = useEnvironmentContext()
+
+  return <pre>{JSON.stringify(getRootNode(), null, 2)}</pre>
+}

packages/solid/src/providers/environment/examples/setup.tsx

@@ -0,0 +1,9 @@
+import { Environment } from '../..'
+
+export const App = () => {
+  return (
+    <iframe title="IFrame Context">
+      <Environment>{/* Your App */}</Environment>
+    </iframe>
+  )
+}

packages/solid/src/providers/environment/examples/usage.tsx

@@ -0,0 +1,7 @@
+import { useEnvironmentContext } from '../use-environment-context'
+
+export const Usage = () => {
+  const environment = useEnvironmentContext()
+
+  return <pre>{JSON.stringify(environment().getRootNode(), null, 2)}</pre>
+}

packages/solid/src/providers/environment/use-environment-context.ts

@@ -7,14 +7,17 @@ export interface EnvironmentContext {
   /**
    * The root node of the application.
    * This is used to determine the window and document objects.
+   * @default document
    */
   getRootNode(): RootNode
   /**
    * The document context for the root node.
+   * @default document
    */
   getDocument(): Document
   /**
    * The window context for the root node.
+   * @default window
    */
   getWindow(): Window & typeof globalThis
 }

packages/vue/src/providers/environment/examples/basic.vue

@@ -1,10 +1,10 @@
 <script setup lang="ts">
 import Environment from '../environment.vue'
-import PrintEnvironment from './print-environment.vue'
+import Usage from './usage.vue'
 </script>
 
 <template>
   <Environment>
-    <PrintEnvironment />
+    <Usage />
   </Environment>
 </template>

packages/vue/src/providers/environment/examples/setup.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import { Environment } from '../'
+</script>
+
+<template>
+  <iframe title="IFrame Context">
+    <Environment><!-- Your App --></Environment>
+  </iframe>
+</template>

packages/vue/src/providers/environment/examples/usage.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import { useEnvironmentContext } from '../'
+
+const environment = useEnvironmentContext()
+</script>
+
+<template>
+  <pre>{{ JSON.stringify(environment?.getRootNode(), null, 2) }}</pre>
+</template>

scripts/package.json

@@ -14,7 +14,8 @@
     "vue:props": "bun run src/generate-vue-props.ts",
     "postvue:props": "bun biome format --write ../packages/vue/src/",
     "play": "bun run src/play.ts",
-    "format:vue": "prettier --write '../**/*.vue'"
+    "format:vue": "prettier --write '../**/*.vue'",
+    "format:mdx": "prettier --write '../**/*.mdx'"
   },
   "dependencies": {
     "@types/fs-extra": "11.0.4",

website/package.json

@@ -20,6 +20,7 @@
     "@uidotdev/usehooks": "2.4.1",
     "@zag-js/anatomy-icons": "0.50.0",
     "@zag-js/docs": "0.50.0",
+    "effect": "3.1.5",
     "next": "14.2.3",
     "next-themes": "0.3.0",
     "pandacss-preset-typography": "0.1.5",

website/src/components/data-attr-table.tsx

@@ -1,16 +1,22 @@
 import { type DataAttrKey, getDataAttrDoc } from '@zag-js/docs'
+import { Effect, pipe } from 'effect'
 import { Box } from 'styled-system/jsx'
 import { Code, Table } from './ui'
 
-type Props = {
+interface Props {
   component: string
   part: string
 }
 
 export const DataAttrTable = (props: Props) => {
   const { component, part } = props
-  const properties = getDataAttrDoc(component as DataAttrKey)[part]
 
+  const properties = Effect.runSync(
+    pipe(
+      Effect.try(() => getDataAttrDoc(component as DataAttrKey)[part]),
+      Effect.catchAll(() => Effect.succeed(null)),
+    ),
+  )
   if (!properties) {
     return null
   }

website/src/components/example.tsx

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { transformerNotationHighlight } from '@shikijs/transformers'
+import { Match } from 'effect'
 import { codeToHtml } from 'shiki'
 import { getServerContext } from '~/lib/server-context'
 import { CodeTabs } from './code-tabs'
@@ -22,28 +23,40 @@ const findExamples = async (props: Props) => {
   const serverContext = getServerContext()
   const component = props.component ?? serverContext.component
 
+  if (!component) return []
+
   return Promise.all(
     ['react', 'solid', 'vue'].map(async (framework) => {
-      const lang = framework === 'vue' ? 'vue' : 'tsx'
+      const extenstion = Match.value(framework).pipe(
+        Match.when('vue', () => 'vue'),
+        Match.orElse(() => 'tsx'),
+      )
+      const examplePath = Match.value(component).pipe(
+        Match.when(
+          () => ['progress-circular', 'progress-linear'].includes(component),
+          () => `components/progress/examples/${component.split('-')[1]}`,
+        ),
+        Match.when(
+          () => ['environment', 'locale'].includes(component),
+          () => `providers/${component}/examples`,
+        ),
+        Match.orElse(() => `components/${component}/examples`),
+      )
 
-      const filename = component?.startsWith('progress')
-        ? `${component.split('-')[1]}/${id}.${lang}`
-        : `${id}.${lang}`
+      const basePath = `../packages/${framework}/src`
+      const fileName = [id, extenstion].join('.')
 
-      const path = join(
-        process.cwd(),
-        `../packages/${framework}/src/components/${
-          component?.startsWith('progress') ? 'progress' : component
-        }/examples/${filename}`,
-      )
-      const content = await readFile(path, 'utf-8').catch(() => 'Example not found')
+      const content = await readFile(
+        join(process.cwd(), basePath, examplePath, fileName),
+        'utf-8',
+      ).catch(() => 'Example not found')
 
       const code = content
         .replaceAll(/from '\.\/icons'/g, `from 'lucide-vue-next'`)
         .replaceAll(/from '\..*'/g, `from '@ark-ui/${framework}'`)
 
       const html = await codeToHtml(code, {
-        lang,
+        lang: extenstion,
         theme: 'github-dark-default',
         transformers: [transformerNotationHighlight()],
       })

website/src/content/pages/guides/closed-components.mdx

@@ -19,8 +19,5 @@ Here's an example of an `Avatar` component that can be used consistently across
 To use the `Avatar` component, pass the `name` and `src` props as shown below:
 
 ```jsx
-<Avatar
-  name="Christian"
-  src="https://avatars.githubusercontent.com/u/1846056?v=4" 
-/>
+<Avatar name="Christian" src="https://avatars.githubusercontent.com/u/1846056?v=4" />
 ```

website/src/content/pages/overview/about.mdx

@@ -15,4 +15,3 @@ We are committed to open source and the power of collaboration. Our work has bee
 ## License
 
 This project is licensed under the terms of the [MIT license](https://github.com/chakra-ui/ark/blob/main/LICENSE).
-

website/src/content/pages/overview/getting-started.mdx

@@ -29,7 +29,7 @@ Install the Ark UI dependency using your preferred package manager.
 
 In this guide, we will be adding a Slider component. Copy the following code to your project.
 
-<Example component="slider" id="basic"  />
+<Example component="slider" id="basic" />
 
 </Step>
 
@@ -51,7 +51,6 @@ Check out the [Styling Components guide](/docs/react/guides/styling) to learn mo
 
 </Step>
 
-
 <Step number="5" title="That's it">
 
 Congratulations! You've successfully set up and styled your components using Ark UI.

website/src/content/pages/overview/introduction.mdx

@@ -19,4 +19,3 @@ Building a company-wide design system or a component library for a client has ne
 ## FAQ
 
 <Faq />
-

website/src/content/pages/providers/environment.mdx

@@ -1,50 +1,45 @@
 ---
 id: environment
 title: Environment
-description: Setup components for a custom environment like IFrames, Shadow DOM or an
-  Electron context.
+description: Setup components for custom environments like IFrames, Shadow DOM, or Electron contexts.
 ---
 
-## Explanation
+## Motivation
 
-Internally, we use
-[Zag.js](https://zagjs.com/overview/composition#custom-window-environment),
-which uses DOM query methods like `document.querySelectorAll` and
-`document.getElementById` to locate elements within the machine.
+We use [Zag.js](https://zagjs.com/overview/composition#custom-window-environment) internally,
+which relies on DOM query methods like `document.querySelectorAll` and `document.getElementById` to locate elements.
+In custom environments such as iframes, Shadow DOM, or Electron, these methods might not work as expected because `document` may not be available.
 
-In custom environments like iframe, Shadow DOM, Electron, etc., the machine
-might not work as expected because `document` may not be available.
+To handle this, you can set a default using the `Environment` component. This ensures the correct root node or document is referenced.
 
-To provide the correct reference to root node or document, you can pass
-`getRootNode` function either to all Ark UI root components, or provide a
-default with this Environment component.
+## Setup
 
-> In shadow DOM, the root node can be derived from calling
-> `element.getRootNode()` method on any element.
+To target custom environments like an iframe, Shadow DOM, or Electron, render the `Environment` component to provide the environment context to all Ark UI components.
 
-## Examples
+<Example id="setup" />
 
-When targeting a custom environment like an iframe, Shadow DOM or Electron, you
-can render the Environment component to provide the environment context to all
-Ark UI child components.
+The `Environment` component will automatically detect the current environment and set the correct environment context.
+However, you can also manually set the `Document` like shown in this React example below:
 
-```tsx
-import { Environment, useEnvironmentContext } from '@ark-ui/react'
-import { useCallback, type ReactNode } from 'react'
+```jsx
+import Frame, { FrameContextConsumer } from 'react-frame-component'
+import { Environment } from '@ark-ui/react'
 
-export const App = (props: { children: ReactNode }) => {
-  const getRootNode = useCallback(() => document, [])
-  return <Environment value={getRootNode}>{props.children}</Environment>
-}
+export const App = () => (
+  <Frame title="IFrame Context">
+    <FrameContextConsumer>
+      {({ document }) => <Environment value={document}>{/* Your App */}</Environment>}
+    </FrameContextConsumer>
+  </Frame>
+)
 ```
 
-### Consuming the environment context
+## Usage
 
-You can use the `useEnvironmentContext` hook to consume the environment context.
+Use the `useEnvironmentContext` hook to access the `RootNode`, `Document`, and `Window`.
 
-It will return `undefined` by default, if the Environment component is not
-rendered as a parent.
+<Example id="usage" />
 
-```tsx
-const { getRootNode, getWindow, getDocument } = useEnvironmentContext()
-```
+## API Reference
+
+<ComponentTypes id="environment" />