@octaviaflow/mdx-components 1.1.3

package/README.md

@@ -0,0 +1,215 @@
+# @octaviaflow/mdx-components
+
+> MDX documentation components for the OctaviaFlow Design System
+
+## Overview
+
+A comprehensive library of React components designed specifically for writing beautiful, consistent documentation in MDX format. These components follow the OctaviaFlow Design System guidelines and provide a rich set of tools for creating engaging technical documentation.
+
+## Installation
+
+```bash
+npm install @octaviaflow/mdx-components
+```
+
+Or with Yarn:
+
+```bash
+yarn add @octaviaflow/mdx-components
+```
+
+Or with Bun:
+
+```bash
+bun add @octaviaflow/mdx-components
+```
+
+## Usage
+
+### In MDX Files
+
+```mdx
+import { H1, H2, P, Code, Accordion } from "@octaviaflow/mdx-components";
+
+<H1>Component Documentation</H1>
+
+<P>
+  This is a paragraph with <Code>inline code</Code> examples.
+</P>
+
+<Accordion title="Advanced Usage">Content goes here...</Accordion>
+```
+
+### With Next.js
+
+```javascript
+// next.config.js
+const withMDX = require("@next/mdx")({
+  extension: /\.mdx?$/,
+  options: {
+    // Add MDX components
+    providerImportSource: "@mdx-js/react",
+  },
+});
+
+module.exports = withMDX({
+  pageExtensions: ["ts", "tsx", "js", "jsx", "md", "mdx"],
+});
+```
+
+### With Storybook
+
+```javascript
+// .storybook/preview.js
+import * as MDXComponents from "@octaviaflow/mdx-components";
+
+export const parameters = {
+  docs: {
+    components: MDXComponents,
+  },
+};
+```
+
+## Available Components
+
+### Typography
+
+- `H1`, `H2`, `H3`, `H4`, `H5`, `H6` - Heading components
+- `P` - Paragraph
+- `Blockquote` - Quotations
+
+### Lists
+
+- `OL` - Ordered list
+- `UL` - Unordered list
+- `LI` - List item
+
+### Layout
+
+- `Grid`, `Row`, `Column` - Grid system
+- `Divider` - Visual separator
+- `Aside` - Sidebar content
+- `Caption` - Captions
+
+### Interactive
+
+- `Accordion` - Collapsible sections
+- `Tabs`, `Tab` - Tabbed content
+- `AnchorLinks`, `AnchorLink` - Navigation
+- `GifPlayer` - Animated GIF player
+
+### Content
+
+- `Code` - Code blocks with syntax highlighting
+- `InlineCode` - Inline code
+- `Preview` - Component previews
+- `Video` - Video embeds
+- `ImageWrapper` - Enhanced images
+
+### Cards
+
+- `ArticleCard` - Article previews
+- `ResourceCard` - Resource links
+- `MiniCard` - Compact cards
+- `CardGroup` - Card containers
+
+### Documentation
+
+- `DoDont`, `DoDontRow` - Best practices
+- `PageDescription` - Page introductions
+- `PageTable` - Documentation tables
+- `InlineNotification` - Alerts
+- `StorybookDemo` - Storybook integration
+- `Title` - Page titles
+- `Link` - Enhanced links
+- `ArtDirection` - Responsive images
+
+## Features
+
+✅ **103 Components** - Comprehensive component library  
+✅ **TypeScript** - Full type definitions included  
+✅ **Accessible** - WCAG 2.1 AA compliant  
+✅ **Themeable** - Uses OctaviaFlow design tokens  
+✅ **Tree-shakeable** - Import only what you need  
+✅ **React 18 & 19** - Compatible with latest React versions
+
+## Requirements
+
+- React 18.0.0 or higher (or React 19.0.0)
+- React DOM 18.0.0 or higher (or React 19.0.0)
+
+## Styling
+
+Components use SCSS and OctaviaFlow design tokens. Import the styles in your application:
+
+```javascript
+import "@octaviaflow/mdx-components/lib/index.css";
+```
+
+Or with SCSS:
+
+```scss
+@import "@octaviaflow/mdx-components/components/index.scss";
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import type { H1Props, CodeProps } from "@octaviaflow/mdx-components";
+```
+
+## Examples
+
+### Code Highlighting
+
+```mdx
+<Code language="javascript">
+  {`
+function hello() {
+  console.log('Hello, World!');
+}
+`}
+</Code>
+```
+
+### Do/Don't Examples
+
+```mdx
+<DoDontRow>
+  <DoDont type="do" caption="Use semantic HTML">
+    <img src="good-example.png" alt="Good example" />
+  </DoDont>
+  <DoDont type="dont" caption="Avoid div soup">
+    <img src="bad-example.png" alt="Bad example" />
+  </DoDont>
+</DoDontRow>
+```
+
+### Tabs
+
+```mdx
+<Tabs>
+  <Tab label="React">React implementation...</Tab>
+  <Tab label="Vue">Vue implementation...</Tab>
+</Tabs>
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](/.github/CONTRIBUTING.md).
+
+## License
+
+Licensed under the [Apache 2.0 License](/LICENSE).
+
+## Telemetry
+
+This package uses OctaviaFlow Telemetry to collect anonymous usage metrics. By installing this package, you agree to telemetry collection. To opt out:
+
+```bash
+export OCTAVIAFLOW_TELEMETRY_DISABLED=1
+```
+
+For more information, see our [Telemetry Documentation](https://github.com/octaviaflow-design-system/telemetry).

package/components/_utils.scss

@@ -0,0 +1,18 @@
+/*
+ * 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.
+ */
+$carbon-mdx-prefix: 'carbon-mdx-components';
+
+@function with-prefix($input) {
+  @return $carbon-mdx-prefix + '--' + $input;
+}
+
+@mixin line-clamp($lines: 2) {
+  display: -webkit-box;
+  overflow: hidden;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: $lines;
+}

package/components/accordion/_accordion.scss

@@ -0,0 +1,35 @@
+/*
+ * 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.
+ */
+
+@use '@carbon/react/scss/spacing' as spacing;
+@use '@carbon/react/scss/type' as type;
+@use '@carbon/react/scss/theme' as theme;
+
+@use '../utils' as *;
+
+.#{with-prefix('accordion')} {
+  color: theme.$text-primary;
+  margin-block-start: spacing.$spacing-06;
+}
+
+// override carbon styles
+.#{with-prefix('accordion')} .ods--accordion__heading {
+  padding-block: spacing.$spacing-04;
+}
+
+// override carbon, accordion inset-inline-end spacing
+.#{with-prefix('accordion')} .ods--accordion__content {
+  padding-inline-end: spacing.$spacing-10;
+}
+
+// override carbon, title font and spacing
+.#{with-prefix('accordion')} .ods--accordion__title {
+  @include type.type-style('heading-02');
+
+  margin: 0 0 0 1rem;
+  padding-inline-start: 0;
+}

package/components/accordion/accordion.stories.jsx

@@ -0,0 +1,33 @@
+/**
+ * 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 { Accordion } from "./accordion";
+import { AccordionItem } from "@carbon/react";
+
+export default {
+  title: "Components/MDX Components/Accordion",
+  component: Accordion,
+  subcomponents: { AccordionItem },
+};
+
+export const Default = (args) => (
+  <Accordion {...args}>
+    <AccordionItem title="Title 1">Content Section</AccordionItem>
+    <AccordionItem title="Title 2">Content Section</AccordionItem>
+    <AccordionItem title="Title 3">Content Section</AccordionItem>
+  </Accordion>
+);

package/components/accordion/accordion.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 { Accordion as CarbonAccordion, Column, Grid } from "@octaviaflow/react";
+import { clsx } from "clsx";
+import PropTypes from "prop-types";
+import React from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+
+export interface AccordionProps {
+  className?: string | null;
+}
+
+/**
+ * The `<Accordion>` and `<AccordionItem>` components are used together to display a list of content
+ * sections that can be toggled open by clicking the respective title of each section.
+ */
+export const Accordion: MdxComponent<AccordionProps> = ({
+  className,
+  ...rest
+}) => (
+  <Grid narrow>
+    <Column sm={4} md={8} lg={8}>
+      <CarbonAccordion
+        size="md"
+        {...rest}
+        className={clsx(className, withPrefix("accordion"))}
+      />
+    </Column>
+  </Grid>
+);
+
+Accordion.propTypes = {
+  /**
+   * Optional class name on the accordion.
+   */
+  className: PropTypes.string,
+};
+
+export default Accordion;

package/components/anchor-links/_anchor-links.scss

@@ -0,0 +1,67 @@
+/*
+ * 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.
+ */
+@use '@carbon/react/scss/spacing' as spacing;
+@use '@carbon/react/scss/theme' as theme;
+@use '@carbon/react/scss/type' as type;
+@use '@carbon/react/scss/breakpoint' as breakpoint;
+@use '@carbon/react/scss/motion' as motion;
+
+@use '../utils' as *;
+
+.#{with-prefix('anchor-links')} {
+  margin-block-start: spacing.$spacing-07;
+
+  + * {
+    margin-block-start: calc(spacing.$spacing-11 - spacing.$spacing-03);
+  }
+
+  .#{with-prefix('anchor-link')} {
+    @include type.type-style('fluid-heading-03', true);
+
+    position: relative;
+    display: inline-block;
+    color: theme.$text-primary;
+    margin-block-end: spacing.$spacing-03;
+    margin-inline-start: spacing.$spacing-06;
+    text-decoration: none;
+    transition: color motion.$duration-fast-02;
+
+    &:hover {
+      color: theme.$link-primary;
+    }
+
+    &::before {
+      position: absolute;
+      color: currentColor;
+      //"↳"
+      content: '\21B3';
+      cursor: pointer;
+      inset-inline-start: -(spacing.$spacing-06);
+    }
+
+    &:focus {
+      outline: 2px solid theme.$link-primary;
+    }
+
+    @media screen and (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
+  }
+
+  .#{with-prefix('list--small')} .#{with-prefix('anchor-link')} {
+    @include type.type-style('body-02');
+
+    margin-block-end: 0;
+  }
+
+  // Multiple Columns
+  .#{with-prefix('multiple-columns')} {
+    @include breakpoint.breakpoint('md') {
+      column-count: 2;
+    }
+  }
+}

package/components/anchor-links/anchor-link.tsx

@@ -0,0 +1,50 @@
+/**
+ * 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 from "react";
+import slugify from "slugify";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+
+interface AnchorLinkProps {
+  to?: string | null;
+  children: string;
+}
+
+export const AnchorLink: MdxComponent<AnchorLinkProps> = ({ to, children }) => {
+  const href = to || `#${slugify(children, { lower: true })}`;
+
+  return (
+    <a className={withPrefix("anchor-link")} href={href} data-anchor-link>
+      {children}
+    </a>
+  );
+};
+
+AnchorLink.propTypes = {
+  /**
+   * Provide the contents of your `AnchorLink`.
+   */
+  children: PropTypes.string.isRequired,
+  /**
+   * By default, the `AnchorLink` slugifys the children you pass in. Use the to prop to override
+   * this target.
+   */
+  to: PropTypes.string,
+};
+
+export default AnchorLink;

package/components/anchor-links/anchor-links.stories.jsx

@@ -0,0 +1,51 @@
+/**
+ * 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 { AnchorLink } from "./anchor-link";
+import { AnchorLinks } from "./anchor-links";
+
+export default {
+  title: "Components/MDX Components/AnchorLinks",
+  component: AnchorLinks,
+  subcomponents: { AnchorLink },
+  argTypes: {
+    small: {
+      control: "boolean",
+    },
+  },
+};
+
+const Template = (args) => (
+  <AnchorLinks {...args}>
+    <AnchorLink>Link 1</AnchorLink>
+    <AnchorLink>Link 2</AnchorLink>
+    <AnchorLink>Link 3</AnchorLink>
+    <AnchorLink>Link 4</AnchorLink>
+    <AnchorLink>Link 5</AnchorLink>
+    <AnchorLink>Link 6</AnchorLink>
+    <AnchorLink>Link 7</AnchorLink>
+  </AnchorLinks>
+);
+
+export const Default = Template.bind({});
+Default.args = {
+  small: false,
+};
+
+export const Small = Template.bind({});
+Small.args = {
+  small: true,
+};

package/components/anchor-links/anchor-links.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, { Children, ReactNode } from "react";
+
+import { MdxComponent } from "../interfaces";
+import { withPrefix } from "../utils";
+
+interface AnchorLinksProps {
+  small?: boolean | null;
+  children: ReactNode;
+}
+
+/**
+ * The `<AnchorLinks>` and `<AnchorLink>` components are used together to display a list of anchor
+ * links for navigation within the page. Use these to link to `<h2>` or `<h3>` anywhere within your
+ * page. As long as the anchor link text and header text matches the link will work.
+ *
+ * For most pages, we recommend starting with a `PageDescription` followed by `AnchorLinks` if the
+ * content is long enough.
+ */
+export const AnchorLinks: MdxComponent<AnchorLinksProps> = ({
+  children,
+  small,
+}) => {
+  const isColumn = Children.count(children) > 4;
+  const classNames = clsx({
+    [withPrefix("list--small")]: small,
+    [withPrefix("multiple-columns")]: isColumn,
+  });
+
+  return (
+    <Grid className={withPrefix("anchor-links")} data-anchor-links-list>
+      <Column sm={4} md={8} lg={8}>
+        <ul className={classNames}>
+          {Children.map(children, (link, i) => (
+            <li key={i}>{link}</li>
+          ))}
+        </ul>
+      </Column>
+    </Grid>
+  );
+};
+
+AnchorLinks.propTypes = {
+  /**
+   * A set of links to be rendered as part of this AnchorLinks component.
+   */
+  children: PropTypes.node as unknown as React.Validator<React.ReactNode>,
+
+  /**
+   * Display small font size.
+   */
+  small: PropTypes.bool,
+};
+
+export default AnchorLinks;

package/components/art-direction/art-direction.stories.jsx

@@ -0,0 +1,44 @@
+/**
+ * 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 { ArtDirection } from "./art-direction";
+import desktop from "./desktop.jpg";
+import mobile from "./mobile.jpg";
+import tablet from "./tablet.jpg";
+
+export default {
+  title: "Components/MDX Components/Images & Video/ArtDirection",
+  component: ArtDirection,
+  argTypes: {
+    children: {
+      control: false,
+    },
+  },
+};
+
+const Template = (args) => (
+  <div style={{ minHeight: "500px" }}>
+    <ArtDirection {...args}>
+      <img alt="mobile" src={mobile} />
+      <img alt="tablet" src={tablet} />
+      <img alt="desktop" src={desktop} />
+    </ArtDirection>
+  </div>
+);
+
+export const Default = Template.bind({});
+Default.args = {};