Merge pull request #356 from Weaverse/docs-markdown

Docs markdown

docs/api/get-selected-product-options.md

@@ -0,0 +1,53 @@
+---
+title: getSelectedProductOptions
+description: The getSelectedProductOption returns the selected product options from the request's search parameters.
+publishedAt: 10-10-2023
+updatedAt: 10-10-2023
+order: 4
+published: true
+---
+
+In a Weaverse Hydrogen Theme, **`getSelectedProductOptions`** serves as an essential utility for capturing customer
+selections on product pages. This function simplifies the process of extracting and handling user-selected product
+variants.
+
+Usage
+-----
+
+This utility is intended for **server-side** use, such as within a route's loader or a component's loader function, and
+is specifically tailored for use on product pages.
+
+```tsx
+// <root>/app/routes/($locale).products.$productHandle.tsx
+
+import { LoaderArgs } from '@shopify/remix-oxygen'
+import { getSelectedProductOptions } from '@weaverse/hydrogen'
+
+export async function loader({ params, request, context }: LoaderArgs) {
+  let { shop, product } = await context.storefront.query(PRODUCT_QUERY, {
+      variables: {
+        handle: params.productHandle,
+        // Use the utility to get selected product options from the request
+        selectedOptions: getSelectedProductOptions(request),
+        country: context.storefront.i18n.country,
+        language: context.storefront.i18n.language
+      }
+    })
+
+
+  // Fetch and return the product data based on the selected options
+  // ...
+}
+```
+
+Return Value
+------------
+
+The **`getSelectedProductOptions`** utility returns an object where the keys are option names (such as "**Color**" or "
+**Size**") and the values are the selected options by the customer as indicated in the request's search parameters.
+
+Scope of Use
+------------
+
+This utility is specifically designed for use on the **product page only** within the Weaverse Hydrogen theme. It is
+**NOT** intended for non-product pages as it relies on the context of a product and its selectable options.

docs/api/index.md

@@ -0,0 +1,5 @@
+---
+title: API References
+description: All the Weaverse Hydrogen APIs info you need. Dive in and get coding.
+order: 3
+---

docs/api/use-item-instance.md

@@ -0,0 +1,67 @@
+---
+title: useItemInstance
+description: The useItemInstance hook provides components the ability to access and manipulate a specific item instance.
+publishedAt: 10-10-2023
+updatedAt: 10-10-2023
+order: 3
+published: true
+---
+
+The **`useItemInstance`** hook is utilized to interact with a distinct item. Developers can access and manage that
+item’s properties and trigger a re-render when necessary.
+
+Usage
+-----
+
+To retrieve the instance of an item, call **`useItemInstance`** with the item's ID as an argument. This ID is a `string`
+that uniquely identifies the item within the page.
+
+```tsx
+import { useItemInstance } from '@weaverse/hydrogen';
+
+function MyComponent() {
+  let instance = useItemInstance('itemId');
+
+  // Interact with the item instance
+  // ...
+
+  return (
+    // Render your component
+  );
+};
+```
+
+Properties
+----------
+
+#### `_id`
+
+* **Type**: **`string`**
+
+* **Description**: The property **`instance._id`** returns the unique identifier of the item.
+
+#### `data`
+
+* **Type**: **`any`**
+
+* **Description**: This property holds the data associated with the item, which can be used to render the item or
+  determine its behavior.
+
+#### `_element`
+
+* **Type**: **`HTMLElement | null`**
+
+* **Description**: Provides a reference to the item's corresponding DOM node, allowing direct manipulation of the item
+  in the DOM.
+
+Methods
+-------
+
+#### `triggerUpdate()`
+
+* **Arguments**: None.
+
+* **Returns**: Void.
+
+* **Description**: When called, **`instance.triggerUpdate()`** will cause the item to re-render. This is useful when the
+  item's state changes and you need to reflect these changes in the UI.

docs/api/use-theme-settings.md

@@ -0,0 +1,53 @@
+---
+title: useThemeSettings
+description: The useThemeSettings hook provides a simple way for Weaverse Hydrogen components to retrieve and utilize the global theme settings.
+publishedAt: 10-10-2023
+updatedAt: 10-10-2023
+order: 1
+published: true
+---
+
+The **`useThemeSettings`** hook is an interface for accessing the global theme settings within a Weaverse Hydrogen
+theme, enabling components to adapt to merchant-configured preferences.
+
+Usage
+-----
+
+Import the hook from `@weaverse/hydrogen` package then call it within a React component to get an object containing the
+current global theme settings.
+
+```tsx
+import { useThemeSettings } from "@weaverse/hydrogen"
+
+export function GlobalStyle() {
+  let settings = useThemeSettings()
+  if (settings) {
+    let {
+      bodyBaseSize,
+      bodyBaseLineHeight,
+      headingBaseSize
+      // more settings...
+    } = settings
+
+    return (
+      <style
+        dangerouslySetInnerHTML={{
+          __html: `
+            :root {
+              --body-base-size: ${bodyBaseSize}px;
+              --body-base-line-height: ${bodyBaseLineHeight};
+              --heading-base-size: ${headingBaseSize}px;
+              --height-nav: ${settings.navHeightMobile}rem;
+            }
+          `
+        }}
+      />
+    )
+  }
+  return null
+}
+```
+
+For a deeper understanding of how global theme settings are established and how they interact with the
+**`useThemeSettings`** hook, you can reference
+the [Global Theme Settings article](/docs/guides/global-theme-settings).

docs/api/use-weaverse.md

@@ -0,0 +1,31 @@
+---
+title: useWeaverse
+description: The useWeaverse hook allows components to access the Weaverse instance specific to each page.
+publishedAt: 10-10-2023
+updatedAt: 10-10-2023
+order: 2
+published: true
+---
+
+The **`useWeaverse`** hook allows components to access the Weaverse instance specific to each page, enabling the retrieval of page data, component instances, and configuration settings within a Weaverse Hydrogen theme.
+
+Usage
+-----
+
+Import the hook from `@weaverse/hydrogen` package then call it within a React Component
+
+```tsx
+import { useWeaverse } from '@weaverse/hydrogen'
+
+function MyComponent() {
+  let { data, itemInstances, elementRegistry } = useWeaverse()
+
+  // Example: Accessing specific component instance data
+  let instance = itemInstances['uniqueComponentId']
+  // ...
+
+  return (
+    // ...
+  )
+}
+```

docs/api/weaverse-client.md

@@ -0,0 +1,70 @@
+---
+title: WeaverseClient
+description: The WeaverseClient class provides developers with a suite of methods to interact with the Weaverse inside a Weaverse Hydrogen Theme.
+publishedAt: 10-10-2023
+updatedAt: 10-10-2023
+order: 0
+published: true
+---
+
+The **`WeaverseClient`** class provides developers with a suite of methods to interact with Weaverse, manage caching
+strategies, and load theme-specific settings and pages.
+
+Initialization
+--------------
+
+Developers construct an instance with appropriate configurations, including environmental variables, storefront
+information, and more, and then inject the instance into the app's load context for global accessibility.
+
+Refer to the [Project Structure article](/docs/guides/project-structure#base-files-explained)
+for a detailed walkthrough on setting up.
+
+Methods
+-------
+
+#### `fetchWithCache`
+
+* **Arguments**:
+
+* **`url`**: **`string`** - The endpoint to which the fetch request is made.
+
+* **`options`**: **`FetchWithCacheOptions`** - Optional. Configurations for the fetch request, including caching
+  strategies and additional request initializations.
+
+* **Returns**: **`Promise<T>`** - A promise that resolves with the fetched data of the generic type **`T`**.
+
+* **Description**: Fetches data from an external API, applying the specified caching strategy.
+
+  Refer to
+  the [Data Fetching and Caching](/docs/guides/fetching-and-caching#fetching-data-from-external-apis)
+  to learn more.
+
+#### `loadThemeSettings`
+
+* **Arguments**:
+
+* **`strategy`**: **`AllCacheOptions`** - Optional. The caching strategy to use when fetching theme settings.
+
+* **Returns**: **`Promise<any>`** - A promise that resolves with the theme settings data.
+
+* **Description**: Loads the theme settings, applying caching if not in design mode.
+
+  Refer to
+  the [Global Theme Settings](/docs/guides/global-theme-settings#load-theme-settings) to
+  learn more.
+
+#### `loadPage`
+
+* **Arguments**:
+
+* **`params`**: **`LoadPageParams`** - Optional. Parameters for loading the page, including caching strategy and other
+  request-specific data.
+
+* **Returns**: **`Promise<WeaverseLoaderData | null>`** - A promise that resolves with the data necessary for rendering
+  a page or **`null`** in case of an error.
+
+* **Description**: Loads the data for a specific page, including configurations and content.
+
+  Refer to
+  the [Rendering a Weaverse Page](/docs/guides/rendering-page#fetching-page-data)
+  to learn more.

docs/api/with-weaverse.md

@@ -0,0 +1,43 @@
+---
+title: withWeaverse
+description: The withWeaverse HOC enhances your root component, allowing it to access Weaverse-specific properties and methods.
+publishedAt: 10-10-2023
+updatedAt: 10-10-2023
+order: 5
+published: true
+---
+
+**`withWeaverse`** HOC is a crucial part of the architecture. It wraps the root component and any error boundaries to
+ensure that Weaverse functionalities are available throughout the application.
+
+Usage
+-----
+
+Implement **`withWeaverse`** in your root component and error boundary components to provide them with Weaverse
+integration. This process allows the components to access the loaded Weaverse theme settings and other context-specific
+data provided by Weaverse.
+
+Here's a basic example of how to wrap your root component with **`withWeaverse`**:
+
+```tsx
+import { withWeaverse } from '@weaverse/hydrogen';
+
+function App() {
+  // Your component logic
+}
+
+export default withWeaverse(App);
+```
+
+Similarly, for an error boundary component:
+
+```tsx
+export const ErrorBoundary = withWeaverse(ErrorBoundaryComponent);
+```
+
+How It Works
+------------
+
+By wrapping a component with **`withWeaverse`**, the component gains access to the Weaverse context, which includes
+theme settings, page configurations, and other essential data loaded via the Weaverse client. This allows for consistent
+use of Weaverse features across the entire app.

docs/deployment/index.md

@@ -0,0 +1,5 @@
+---
+title: Deployment
+description: Ready to go live? Find out how to push your Weaverse Hydrogen project to different platforms. It's simpler than you think!
+order: 2
+---