@octaviaflow/mdx-components 1.1.3

package/components/tabs/tab-list.tsx

@@ -0,0 +1,48 @@
+/**
+ * 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 PropTypes from "prop-types";
+import React, { useContext } from "react";
+
+import { MdxComponent, NonScalarNode } from "../interfaces";
+import { withPrefix } from "../utils";
+import { TabContext } from "./tabs";
+
+interface TabListProps {
+  _id: string;
+  children: NonScalarNode;
+}
+
+export const TabList: MdxComponent<TabListProps> = ({ _id, children }) => {
+  const { activeTab } = useContext(TabContext);
+
+  return (
+    <ul className={withPrefix("tab-list")} role="tablist">
+      {React.Children.map(children, (child, index) => {
+        return React.cloneElement(child, {
+          _id: `${_id}__${index}`,
+          active: activeTab === index,
+          index,
+          tab: true,
+        });
+      })}
+    </ul>
+  );
+};
+
+TabList.propTypes = {
+  _id: PropTypes.string.isRequired,
+  children: PropTypes.array.isRequired,
+};

package/components/tabs/tab.tsx

@@ -0,0 +1,125 @@
+/**
+ * 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 PropTypes from "prop-types";
+import React, {
+  KeyboardEvent,
+  ReactNode,
+  useCallback,
+  useContext,
+} from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+import { TabContext } from "./tabs";
+
+interface TabProps {
+  _id: string;
+  active?: boolean | null;
+  children: ReactNode;
+  index: number;
+  label: string;
+  tab?: boolean | null;
+}
+
+export const Tab: MdxComponent<TabProps> = ({
+  _id,
+  label,
+  active,
+  index,
+  tab,
+  children,
+}) => {
+  const { setActiveTab, tabList } = useContext(TabContext);
+  const buttonRef = useCallback((ref) => tabList.push(ref), [tabList]);
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    let nextButton;
+    switch (e.key) {
+      case "End":
+        e.preventDefault();
+        tabList[tabList.length - 1]?.focus();
+        break;
+      case "Home":
+        e.preventDefault();
+        tabList[0]?.focus();
+        break;
+      case "ArrowLeft":
+        e.preventDefault();
+        nextButton = tabList[index - 1] || tabList[tabList.length - 1];
+        nextButton?.focus();
+        break;
+      case "ArrowRight":
+        e.preventDefault();
+        nextButton = tabList[index + 1] || tabList[0];
+        nextButton?.focus();
+        break;
+      default:
+    }
+  };
+
+  if (tab) {
+    return (
+      <li role="presentation">
+        <button
+          className={withPrefix("tab")}
+          ref={buttonRef}
+          onKeyDown={onKeyDown}
+          onClick={() => setActiveTab(index)}
+          onFocus={() => setActiveTab(index)}
+          type="button"
+          role="tab"
+          id={`${_id}--tab`}
+          tabIndex={!active ? -1 : 0}
+          aria-selected={active || undefined}
+        >
+          {label}
+        </button>
+      </li>
+    );
+  }
+
+  return (
+    <section
+      className={withPrefix("tab-panel")}
+      hidden={!active}
+      role="tabpanel"
+      id={`${_id}--panel`}
+      aria-labelledby={`${_id}--tab`}
+    >
+      {children}
+    </section>
+  );
+};
+
+Tab.propTypes = {
+  /** tab id */
+  _id: PropTypes.string.isRequired,
+  /** Set active tab */
+  active: PropTypes.bool,
+  /** Provide the contents of the tab */
+  children: PropTypes.node as unknown as React.Validator<React.ReactNode>,
+  /** tab index */
+  index: PropTypes.number.isRequired,
+  /** Set tab label */
+  label: PropTypes.string.isRequired,
+  /** tab */
+  tab: PropTypes.bool,
+};
+
+Tab.defaultProps = {
+  _id: "none",
+  index: 0,
+};

package/components/tabs/tabs.stories.jsx

@@ -0,0 +1,54 @@
+/**
+ * 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 { Tab } from "./tab";
+import { Tabs } from "./tabs";
+
+export default {
+  title: "Components/MDX Components/Tabs",
+  component: Tabs,
+  subcomponents: { Tab },
+};
+
+const Template = (args) => (
+  <Tabs {...args}>
+    <Tab label="Tab 1">
+      Maecenas ultrices sem nec blandit dictum. ermentum ullamcorper pretium.
+      Duis turpis elit, facilisis nec elit id, fermentum porttitor nisl. Nulla
+      dignissim euismod maximus. Cras euismod facilisis rutrum. Etiam nisi sem,
+      malesuada auctor pretium vel, ullamcorper sed mi. In hac habitasse platea
+      dictumst.
+    </Tab>
+    <Tab label="Tab 2">
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean feugiat ex
+      massa, in tincidunt ipsum tempor in. Maecenas ultrices sem nec blandit
+      dictum. ermentum ullamcorper pretium. Duis turpis elit, facilisis nec elit
+      id, fermentum porttitor nisl. Nulla dignissim euismod maximus. Cras
+      euismod facilisis rutrum.
+    </Tab>
+    <Tab label="Tab 3">
+      Duis turpis elit, facilisis nec elit id, fermentum porttitor nisl. Nulla
+      dignissim euismod maximus. Cras euismod facilisis rutrum. Etiam nisi sem,
+      malesuada auctor pretium vel, ullamcorper sed mi. In hac habitasse platea
+      dictumst. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean
+      feugiat ex massa, in tincidunt ipsum tempor in.
+    </Tab>
+  </Tabs>
+);
+
+export const Default = Template.bind({});
+Default.args = {};

package/components/tabs/tabs.tsx

@@ -0,0 +1,78 @@
+/**
+ * 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 PropTypes from "prop-types";
+import React, { createContext, useEffect, useRef, useState } from "react";
+
+import { MdxComponent, NonScalarNode } from "../interfaces";
+import { mediaQueries, useId, useMatchMedia } from "../utils";
+import Select from "./select";
+import { TabList } from "./tab-list";
+
+interface TabContextInterface {
+  setActiveTab(tab: number): void;
+  activeTab: number;
+  tabList: Array<HTMLButtonElement>;
+}
+
+const TabContext = createContext<TabContextInterface>({
+  setActiveTab: () => undefined,
+  activeTab: -1,
+  tabList: [],
+});
+
+interface TabsProps {
+  children: NonScalarNode;
+}
+
+/**
+ * The `<Tabs>` and `<Tab>` components are used together to display and swap between content.
+ */
+export const Tabs: MdxComponent<TabsProps> = (props) => {
+  const tabList = useRef([]);
+  const [activeTab, setActiveTab] = useState(0);
+  const isMd = useMatchMedia(mediaQueries.md);
+  const id = useId("tabs");
+
+  // clear tablist when unmounted (switching between Select and TabList)
+  useEffect(() => () => {
+    tabList.current = [];
+  });
+
+  return (
+    <TabContext.Provider
+      value={{ setActiveTab, activeTab, tabList: tabList.current }}
+    >
+      {isMd && <TabList _id={id}>{props.children}</TabList>}
+      {!isMd && <Select _id={id}>{props.children}</Select>}
+      {React.Children.map(props.children, (child, index) => {
+        return React.cloneElement(child, {
+          _id: `${id}__${index}`,
+          active: activeTab === index,
+          index,
+        });
+      })}
+    </TabContext.Provider>
+  );
+};
+
+Tabs.propTypes = {
+  /** Provide tab children */
+  children: PropTypes.array.isRequired,
+};
+
+Tabs.displayName = "Tabs";
+
+export { TabContext };

package/components/title/title.stories.jsx

@@ -0,0 +1,43 @@
+/**
+ * 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 { Title } from "./title";
+import { P } from "../markdown/p";
+
+export default {
+  title: "Components/MDX Components/Title",
+  component: Title,
+  argTypes: {
+    children: {
+      control: false,
+    },
+    className: {
+      control: false,
+    },
+  },
+};
+
+const Template = (args) => (
+  <>
+    <Title {...args}>Lorem ipsum</Title>
+    <P>
+      This is the element after the title with its default top margin removed.
+    </P>
+  </>
+);
+
+export const Default = Template.bind({});
+Default.args = {};

package/components/title/title.tsx

@@ -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 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 PropTypes from "prop-types";
+import React, { ReactNode } from "react";
+
+import { H4 } from "../markdown/h4";
+import { MdxComponent } from "../interfaces";
+
+interface TitleProps {
+  children: ReactNode;
+  className?: string | null;
+}
+
+/**
+ * The `<Title>` component is used to provide a title to a subsequent component
+ * (table, image, video, code block). The Title should be used in favor of other
+ * techniques for bolded text (h4s) to preserve page structure and heading hierarchy.
+ */
+export const Title: MdxComponent<TitleProps> = ({ children, className }) => (
+  <H4 autolink={false} className={className}>
+    {children}
+  </H4>
+);
+
+Title.propTypes = {
+  /**
+   * Provide the contents of Title
+   */
+  children: PropTypes.node as unknown as React.Validator<React.ReactNode>,
+  /**
+   * Optional class name on the title.
+   */
+  className: PropTypes.string,
+};

package/components/utils.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 { breakpoints } from "@octaviaflow/layout";
+import { useEffect, useState } from "react";
+
+const prefix = "carbon-mdx-components";
+const mediaQueries = {
+  sm: `(min-width: ${breakpoints.sm.width})`,
+  md: `(min-width: ${breakpoints.md.width})`,
+  lg: `(min-width: ${breakpoints.lg.width})`,
+  xlg: `(min-width: ${breakpoints.xlg.width})`,
+  max: `(min-width: ${breakpoints.max.width})`,
+};
+let globalIndex = 0;
+
+/**
+ * Queries the window if it exists.
+ * @param {string} query of the dimensions needed
+ * @returns the matchMedia function
+ */
+const getMatchMedia = (query: string) => {
+  return typeof window !== "undefined" && window.matchMedia
+    ? window.matchMedia(query)
+    : null;
+};
+
+/**
+ * Gives an ID to the markdown components.
+ * @param {string} label component name string
+ * @returns string for component ID
+ */
+const useId = (label: string) => {
+  // TODO: delete this hook and use react 18 useId instead.
+  const [id] = useState(++globalIndex);
+
+  return `cp__${label}__${id}`;
+};
+
+/**
+ * Function that returns the viewport media dimensions.
+ * @param {string} query string
+ * @returns boolean stating if it matches viewport dimensions
+ */
+const useMatchMedia = (query: string) => {
+  const [matches, setMatches] = useState(getMatchMedia(query)?.matches);
+
+  useEffect(() => {
+    const matchMediaResult = getMatchMedia(query);
+    /**
+     *
+     * @param {any} e event
+     * @param {(
+     *   boolean |
+     *   ((prevState: boolean | undefined) => boolean | undefined) |
+     *   undefined
+     * )} e.matches boolean stating if it matches
+     */
+    const updateMatch = (e: {
+      matches:
+        | boolean
+        | ((prevState: boolean | undefined) => boolean | undefined)
+        | undefined;
+    }) => {
+      setMatches(e.matches);
+    };
+
+    matchMediaResult?.addEventListener("change", updateMatch);
+
+    return () => {
+      matchMediaResult?.removeEventListener("change", updateMatch);
+    };
+  }, [query]);
+
+  return matches;
+};
+
+/**
+ * Adds a prefix specific to the carbon platform mdx components to the provided string. This is
+ * often used in conjunction with the scss utility `with-prefix` to assign unique class names to
+ * styles for components.
+ *
+ * @param {string} className The string to which to add a prefix.
+ * @returns A prefixed string.
+ */
+function withPrefix(className: string) {
+  return prefix + "--" + className;
+}
+
+export { mediaQueries, useId, useMatchMedia, withPrefix };

package/components/video/_video.scss

@@ -0,0 +1,89 @@
+/*
+ * Copyright OctaviaFlow 2021, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+@use '@carbon/react/scss/motion' as motion;
+@use '@carbon/react/scss/colors' as colors;
+@use '@carbon/react/scss/theme' as theme;
+@use '@carbon/react/scss/spacing' as spacing;
+
+@use '../utils' as *;
+
+.#{with-prefix('video-container')} {
+  position: relative;
+  display: table;
+  inline-size: 100%;
+
+  .#{with-prefix('video')} {
+    block-size: 100%;
+    inline-size: 100%;
+  }
+
+  div.#{with-prefix('video-button')} {
+    position: absolute;
+    z-index: 10;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 50%;
+    margin: auto;
+    background-color: colors.$blue-60;
+    block-size: 4.5rem;
+    inline-size: 4.5rem;
+    inset-block: 0% 0%;
+    inset-inline: 0% 0%;
+    transition: all motion.$duration-moderate-01 motion(entrance, productive);
+
+    @media screen and (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
+
+    &:focus {
+      outline: 2px solid theme.$focus;
+      outline-offset: -2px;
+    }
+
+    &:hover {
+      background-color: colors.$gray-90;
+      opacity: 0.8;
+    }
+  }
+
+  div.#{with-prefix('video-button')} > svg {
+    fill: theme.$icon-inverse;
+    margin-inline-start: spacing.$spacing-02;
+    transition: all motion.$duration-moderate-01 motion(entrance, productive);
+
+    @media screen and (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
+  }
+
+  div.#{with-prefix('video--is-playing')} > svg {
+    margin-inline-start: 0;
+  }
+
+  // iframe
+  .#{with-prefix('vimeo')} {
+    position: relative;
+    overflow: hidden;
+    block-size: 0;
+    // hack to allow vimeo videos to display correctly and assume full inline-size available
+    padding-block-end: 56.543%;
+
+    iframe {
+      position: absolute;
+      block-size: 100%;
+      inline-size: 100%;
+      inset-block-start: 0;
+      inset-inline-start: 0;
+    }
+  }
+
+  &:not(:hover) div.#{with-prefix('video--is-playing')},
+  &:not(:hover) div.#{with-prefix('video--is-playing')} > svg {
+    opacity: 0;
+  }
+}

package/components/video/video.stories.jsx

@@ -0,0 +1,45 @@
+/**
+ * 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 { Video } from "./video";
+import localPoster from "./local-poster.jpeg";
+import localVideo from "./local-video.mp4";
+
+export default {
+  title: "Components/MDX Components/Images & Video/Video",
+  component: Video,
+  argTypes: {
+    poster: {
+      type: "string",
+    },
+    src: {
+      type: "string",
+    },
+    vimeoId: {
+      type: "string",
+    },
+  },
+};
+
+const Template = (args) => (
+  <Video src={localVideo} poster={localPoster} {...args} />
+);
+
+export const Default = Template.bind({});
+Default.args = {
+  width: 720,
+  height: 405,
+};