@octaviaflow/mdx-components 1.1.3

package/components/markdown/h1.tsx

@@ -0,0 +1,92 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+ * Copyright OctaviaFlow 2022, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Column, Grid } from "@octaviaflow/react";
+import { clsx } from "clsx";
+import PropTypes from "prop-types";
+import React, { ReactNode } from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+import AutolinkHeader from "./autolink-header/autolink-header";
+
+interface H1Props {
+  children: ReactNode;
+  className?: string | null;
+  headingClassName?: string | null;
+  [otherProp: string]: unknown;
+}
+
+/**
+ * For MDX files, steer away from using JSX components
+ * for headings in favor of standard markdown syntax.
+ *
+ * It’s generally considered
+ * <a href="https://webaim.org/techniques/semanticstructure/#contentstructure">best practice</a>
+ *  to include just one h1 heading per page.
+ * This heading signals the title or primary subject matter of the content to your audience.
+ * Because the title component generated at the top of each page already uses an h1 heading,
+ *  we recommend using h2 tags for section headings within your content.
+ *
+ *```
+ * # This is a heading 1
+ * ## This is a heading 2
+ * ### This is a heading 3
+ * #### This is a heading 4
+ * ##### This is a heading 5
+ * ###### This is a heading 6
+ * ```
+ */
+export const H1: MdxComponent<H1Props> = ({
+  children,
+  className,
+  headingClassName,
+  ...rest
+}) => {
+  return (
+    <Grid
+      className={clsx(
+        withPrefix("header"),
+        withPrefix("h2-container"),
+        className,
+      )}
+      {...rest}
+    >
+      <Column sm={4} md={8} lg={8}>
+        <AutolinkHeader
+          is="h1"
+          className={clsx(withPrefix("h1"), headingClassName)}
+        >
+          {children}
+        </AutolinkHeader>
+      </Column>
+    </Grid>
+  );
+};
+
+H1.propTypes = {
+  /**
+   * String title for Header
+   */
+  children: PropTypes.node as unknown as React.Validator<React.ReactNode>,
+  /**
+   * Specify optional className for container element
+   */
+  className: PropTypes.string,
+  /**
+   * Specify optional className for header element
+   */
+  headingClassName: PropTypes.string,
+};

package/components/markdown/h2.tsx

@@ -0,0 +1,85 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+ * Copyright OctaviaFlow 2022, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Column, Grid } from "@octaviaflow/react";
+import { clsx } from "clsx";
+import PropTypes from "prop-types";
+import React, { ReactNode } from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+import AutolinkHeader from "./autolink-header/autolink-header";
+
+interface H2Props {
+  children: ReactNode;
+  className?: string | null;
+  headingClassName?: string | null;
+  noAnchor?: boolean | null;
+  [otherProp: string]: unknown;
+}
+
+export const H2: MdxComponent<H2Props> = ({
+  children,
+  className,
+  headingClassName,
+  noAnchor,
+  ...rest
+}) => {
+  return (
+    <Grid
+      className={clsx(
+        withPrefix("header"),
+        withPrefix("h2-container"),
+        className,
+      )}
+      {...rest}
+    >
+      <Column sm={4} md={8} lg={8}>
+        {noAnchor && (
+          <h2 className={clsx(withPrefix("h2"), headingClassName)}>
+            {children}
+          </h2>
+        )}
+        {!noAnchor && (
+          <AutolinkHeader
+            is="h2"
+            className={clsx(withPrefix("h2"), headingClassName)}
+          >
+            {children}
+          </AutolinkHeader>
+        )}
+      </Column>
+    </Grid>
+  );
+};
+
+H2.propTypes = {
+  /**
+   * String title for Header
+   */
+  children: PropTypes.node as unknown as React.Validator<React.ReactNode>,
+  /**
+   * Specify optional className for container element
+   */
+  className: PropTypes.string,
+  /**
+   * Specify optional className for header element
+   */
+  headingClassName: PropTypes.string,
+  /**
+   * Do not render the autolink anchor
+   */
+  noAnchor: PropTypes.bool,
+};

package/components/markdown/h3.tsx

@@ -0,0 +1,72 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+ * Copyright OctaviaFlow 2022, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Column, Grid } from "@octaviaflow/react";
+import { clsx } from "clsx";
+import PropTypes from "prop-types";
+import React, { ReactNode } from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+import AutolinkHeader from "./autolink-header/autolink-header";
+
+interface H3Props {
+  children: ReactNode;
+  className?: string | null;
+  headingClassName?: string | null;
+  [otherProp: string]: unknown;
+}
+
+export const H3: MdxComponent<H3Props> = ({
+  children,
+  className,
+  headingClassName,
+  ...rest
+}) => {
+  return (
+    <Grid
+      className={clsx(
+        withPrefix("header"),
+        withPrefix("h3-container"),
+        className,
+      )}
+      {...rest}
+    >
+      <Column sm={4} md={8} lg={8}>
+        <AutolinkHeader
+          is="h3"
+          className={clsx(withPrefix("h3"), headingClassName)}
+        >
+          {children}
+        </AutolinkHeader>
+      </Column>
+    </Grid>
+  );
+};
+
+H3.propTypes = {
+  /**
+   * String title for Header
+   */
+  children: PropTypes.node as unknown as React.Validator<React.ReactNode>,
+  /**
+   * Specify optional className for container element
+   */
+  className: PropTypes.string,
+  /**
+   * Specify optional className for header element
+   */
+  headingClassName: PropTypes.string,
+};

package/components/markdown/h4.tsx

@@ -0,0 +1,73 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+ * Copyright OctaviaFlow 2022, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Column, Grid } from "@octaviaflow/react";
+import { clsx } from "clsx";
+import PropTypes from "prop-types";
+import React, { ReactNode } from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+
+interface H4Props {
+  autolink?: boolean | null;
+  children: ReactNode;
+  className?: string | null;
+  headingClassName?: string | null;
+  [otherProp: string]: unknown;
+}
+
+export const H4: MdxComponent<H4Props> = ({
+  autolink = true,
+  children,
+  className,
+  headingClassName,
+  ...rest
+}) => {
+  const Component = autolink ? "h4" : "p";
+
+  return (
+    <Grid
+      className={clsx(
+        withPrefix("header"),
+        withPrefix("h4-container"),
+        className,
+      )}
+      {...rest}
+    >
+      <Column sm={4} md={8} lg={8}>
+        <Component className={clsx(withPrefix("h4"), headingClassName)}>
+          {children}
+        </Component>
+      </Column>
+    </Grid>
+  );
+};
+
+H4.propTypes = {
+  autolink: PropTypes.bool,
+  /**
+   * String title for Header
+   */
+  children: PropTypes.node as unknown as React.Validator<React.ReactNode>,
+  /**
+   * Specify optional className for container element
+   */
+  className: PropTypes.string,
+  /**
+   * Specify optional className for header element
+   */
+  headingClassName: PropTypes.string,
+};

package/components/markdown/h5.tsx

@@ -0,0 +1,59 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+ * Copyright OctaviaFlow 2022, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Column, Grid } from "@octaviaflow/react";
+import { clsx } from "clsx";
+import PropTypes from "prop-types";
+import React, { ReactNode } from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+
+interface H5Props {
+  children: ReactNode;
+  className?: string | null;
+  headingClassName?: string | null;
+  [otherProp: string]: unknown;
+}
+
+export const H5: MdxComponent<H5Props> = ({
+  children,
+  className,
+  headingClassName,
+  ...rest
+}) => {
+  return (
+    <Grid className={clsx(withPrefix("h5-container"), className)} {...rest}>
+      <Column sm={4} md={8} lg={8}>
+        <h5 className={clsx(withPrefix("h5"), headingClassName)}>{children}</h5>
+      </Column>
+    </Grid>
+  );
+};
+
+H5.propTypes = {
+  /**
+   * String title for Header
+   */
+  children: PropTypes.node as unknown as React.Validator<React.ReactNode>,
+  /**
+   * Specify optional className for container element
+   */
+  className: PropTypes.string,
+  /**
+   * Specify optional className for header element
+   */
+  headingClassName: PropTypes.string,
+};

package/components/markdown/h6.tsx

@@ -0,0 +1,59 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+ * Copyright OctaviaFlow 2022, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Column, Grid } from "@octaviaflow/react";
+import { clsx } from "clsx";
+import PropTypes from "prop-types";
+import React, { ReactNode } from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+
+interface H6Props {
+  children: ReactNode;
+  className?: string | null;
+  headingClassName?: string | null;
+  [otherProp: string]: unknown;
+}
+
+export const H6: MdxComponent<H6Props> = ({
+  children,
+  className,
+  headingClassName,
+  ...rest
+}) => {
+  return (
+    <Grid className={clsx(withPrefix("h6-container"), className)} {...rest}>
+      <Column sm={4} md={8} lg={8}>
+        <h6 className={clsx(withPrefix("h6"), headingClassName)}>{children}</h6>
+      </Column>
+    </Grid>
+  );
+};
+
+H6.propTypes = {
+  /**
+   * String title for Header
+   */
+  children: PropTypes.node as unknown as React.Validator<React.ReactNode>,
+  /**
+   * Specify optional className for container element
+   */
+  className: PropTypes.string,
+  /**
+   * Specify optional className for header element
+   */
+  headingClassName: PropTypes.string,
+};

package/components/markdown/headings.stories.jsx

@@ -0,0 +1,52 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+ * Copyright IBM Corp. 2022, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from "react";
+import { H1 } from "./h1";
+import { H2 } from "./h2";
+import { H3 } from "./h3";
+import { H4 } from "./h4";
+import { H5 } from "./h5";
+import { H6 } from "./h6";
+
+export default {
+  title: "Components/MDX Components/Markdown/Headings",
+  component: H1,
+  argTypes: {
+    children: {
+      control: false,
+    },
+    className: {
+      control: false,
+    },
+    headingClassName: {
+      control: false,
+    },
+  },
+};
+
+const H1Template = (args) => (
+  <>
+    <H1 {...args}>This is a Heading 1</H1>
+    <H2 {...args}>This is a Heading 2</H2>
+    <H3 {...args}>This is a Heading 3</H3>
+    <H4 {...args}>This is a Heading 4</H4>
+    <H5 {...args}>This is a Heading 5</H5>
+    <H6 {...args}>This is a Heading 6</H6>
+  </>
+);
+
+export const Default = H1Template.bind({});
+Default.args = {};

package/components/markdown/li.tsx

@@ -0,0 +1,55 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+ * Copyright OctaviaFlow 2022, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { ListItem } from "@octaviaflow/react";
+import { clsx } from "clsx";
+import PropTypes from "prop-types";
+import React, { ReactNode } from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+const { Provider, Consumer: LiConsumer } = React.createContext<LiContext>({
+  hasListItemParent: false,
+});
+
+interface LiProps {
+  children: ReactNode;
+  className?: string | null;
+  [otherProp: string]: unknown;
+}
+
+interface LiContext {
+  hasListItemParent: boolean;
+}
+
+export const LI: MdxComponent<LiProps> = ({ children, className, ...rest }) => (
+  <ListItem className={clsx(className, withPrefix("list-item"))} {...rest}>
+    <Provider value={{ hasListItemParent: true }}>{children}</Provider>
+  </ListItem>
+);
+
+LI.propTypes = {
+  /**
+   * String title for Header
+   */
+  children: PropTypes.node as unknown as React.Validator<React.ReactNode>,
+  /**
+   * Specify optional className for container element
+   */
+  className: PropTypes.string,
+};
+
+export type { LiProps };
+export { LiConsumer };

package/components/markdown/ol.stories.jsx

@@ -0,0 +1,47 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+ * Copyright IBM Corp. 2022, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from "react";
+import { LI } from "./li";
+import { OL } from "./ol";
+
+const stories = {
+  title: "Components/MDX Components/Markdown/OL",
+  component: OL,
+  argTypes: {
+    children: {
+      control: false,
+    },
+    className: {
+      control: false,
+    },
+  },
+};
+
+export default stories;
+
+const Template = (args) => (
+  <div style={{ paddingLeft: "1rem" }}>
+    <OL {...args}>
+      <LI>list item 1</LI>
+      <LI>list item 2</LI>
+      <LI>list item 3</LI>
+    </OL>
+  </div>
+);
+
+export const Default = Template.bind({});
+Default.args = {};

package/components/markdown/ol.tsx

@@ -0,0 +1,93 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+ * Copyright OctaviaFlow 2022, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Column, Grid, OrderedList } from "@octaviaflow/react";
+import { clsx } from "clsx";
+import PropTypes from "prop-types";
+import React, { ReactElement } from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+import { LiConsumer, LiProps } from "./li";
+
+interface OlProps {
+  children: ReactElement | ReactElement[]; // This is how the types would be in TypeScript
+  className?: string | null;
+  [otherProp: string]: unknown;
+}
+
+/**
+ * For MDX files, steer away from using JSX components
+ * for lists in favor of standard markdown syntax.
+ *
+ *```
+ * 1. First ordered list item
+ * 1. In markdown, the actual numbers don’t matter, just that it’s a number
+ * 2. In markdown, the actual numbers don’t matter, just that it’s a number
+ * ```
+ */
+export const OL: MdxComponent<OlProps> = ({ children, className, ...rest }) => {
+  return (
+    <LiConsumer>
+      {(value) => {
+        if (value.hasListItemParent) {
+          return (
+            <OrderedList
+              isExpressive
+              className={clsx(className, withPrefix("list"), withPrefix("ol"))}
+              nested
+              {...rest}
+            >
+              {children}
+            </OrderedList>
+          );
+        } else {
+          return (
+            <Grid className={withPrefix("list-container")}>
+              <Column sm={4} md={8} lg={8}>
+                <OrderedList
+                  isExpressive
+                  className={clsx(
+                    className,
+                    withPrefix("list"),
+                    withPrefix("ol"),
+                  )}
+                  {...rest}
+                >
+                  {children}
+                </OrderedList>
+              </Column>
+            </Grid>
+          );
+        }
+      }}
+    </LiConsumer>
+  );
+};
+
+OL.propTypes = {
+  /**
+   * Child LI elements
+   */
+  children: PropTypes.oneOfType([
+    PropTypes.arrayOf(PropTypes.element.isRequired).isRequired,
+    PropTypes.element.isRequired,
+  ]).isRequired,
+
+  /**
+   * Specify optional className for container element
+   */
+  className: PropTypes.string,
+};