Create docs-ui package with LinkableHeading component (#1401)

* Initial commit

* Fix start

* Update package dependencies

* WIP - add LinkableHeading to package

* ditto

* Use workspace braid

* Update crackle

* Remove stub component

* Add VE dep

* Rename package from documentation-design to docs-ui

* Add README

* Use original LinkableHeading component within Braid site

* Add changeset

* Fix package build step

* Build script fix

* Update readme

* Write real changeset

* Removing docs-ui from site until adoption PR

* Add docs ui logo

* Add logo to README

* Icon test

* Add dark mode icon and update formatting in readme

* Add github light mode only tag to svg

---------

Co-authored-by: Michael Taranto <[email protected]>

.changeset/funny-scissors-invent.md

@@ -0,0 +1,13 @@
+---
+'@braid-design-system/docs-ui': major
+---
+
+Create new package named `docs-ui`.
+
+This package will contain components for building documentation sites with a consistent user experience to the [Braid Design System] website.
+
+Currently, this package contains:
+* A single component: `LinkableHeading`.
+* A README.md for documenting this package and all its components.
+
+[Braid Design System]: https://seek-oss.github.io/braid-design-system/

.eslintrc.js

@@ -9,6 +9,7 @@ module.exports = {
       files: ['*.{js,ts,tsx}'],
       excludedFiles: [
         '*.{docs,gallery,screenshots,stories}.tsx',
+        'packages/docs-ui/**/*.{ts,tsx}',
         'site/**/*.{ts,tsx}',
       ],
       rules: {
@@ -25,5 +26,16 @@ module.exports = {
         ],
       },
     },
+    {
+      files: ['packages/docs-ui/**/*.{js,ts,tsx}'],
+      rules: {
+        'no-restricted-imports': [
+          'error',
+          {
+            patterns: ['braid-src/**', 'site/**', '**/site/**'],
+          },
+        ],
+      },
+    },
   ],
 };

package.json

@@ -8,6 +8,7 @@
     "start": "nx run site:start",
     "start:playroom": "nx run site:start:playroom",
     "build": "nx run braid-design-system:build",
+    "build:docs-ui": "nx run docs-ui:build",
     "build:site": "nx run site:build",
     "storybook": "nx run braid-design-system:storybook",
     "storybook:build": "nx run braid-design-system:storybook:build",
@@ -24,7 +25,7 @@
     "deploy": "node scripts/deploy.js",
     "post-commit-status": "node scripts/postCommitStatus.js",
     "release": "pnpm prepare-publish && changeset publish && pnpm build:site && pnpm run deploy",
-    "prepare-publish": "pnpm build && tsx scripts/copyReadme.cts",
+    "prepare-publish": "pnpm build && pnpm build:docs-ui && tsx scripts/copyReadme.cts",
     "version": "changeset version && tsx scripts/versionComponentUpdates.cts && pnpm install --lockfile-only",
     "changeset": "EDITOR=scripts/writeBraidFrontMatter.js ./node_modules/.bin/changeset add --open"
   },
@@ -85,6 +86,7 @@
   "packageManager": "[email protected]",
   "pnpm": {
     "overrides": {
+      "@braid-design-system/docs-ui": "workspace:*",
       "@braid-design-system/generate-component-docs": "workspace:*",
       "@braid-design-system/source.macro": "workspace:*",
       "braid-design-system": "workspace:*"

packages/braid-design-system/package.json

@@ -123,6 +123,7 @@
     "themes/wireframe"
   ],
   "scripts": {
+    "dev": "crackle dev --webpack",
     "build": "crackle package",
     "codemod": "rm -rf ./codemod/dist && cp -r ../codemod/dist ./codemod/dist",
     "preformat:eslint": "ignore-sync .eslintignore-sync",

packages/docs-ui/.gitignore

@@ -0,0 +1,3 @@
+# managed by crackle
+/dist
+# end managed by crackle

packages/docs-ui/README.md

@@ -0,0 +1,39 @@
+<img src="https://raw.githubusercontent.com/seek-oss/braid-design-system/HEAD/packages/docs-ui/images/braid-docs-ui-logo.svg#gh-light-mode-only" alt="Braid Docs UI" title="Braid Docs UI" width="80px">
+<img src="https://raw.githubusercontent.com/seek-oss/braid-design-system/HEAD/packages/docs-ui/images/braid-docs-ui-logo-inverted.svg#gh-dark-mode-only" alt="Braid Docs UI" title="Braid Docs UI" width="80px" />
+<br/>
+
+# docs-ui
+
+Components for building documentation sites with a consistent user experience to the [Braid Design System] website.
+
+```bash
+npm install @braid-design-system/docs-ui
+```
+
+- [LinkableHeading](#linkableheading)
+
+## Usage
+
+### `LinkableHeading`
+
+A heading wrapped in a link to a hash that is generated based on the heading content, enabling deep links within documentation pages.
+
+#### Example
+
+```tsx
+import { LinkableHeading } from '@braid-design-system/docs-ui';
+
+<LinkableHeading>Section heading</LinkableHeading>;
+```
+
+#### Props
+
+| props     | value            | description                                                                                                                                                               |
+| --------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| level     | [`HeadingLevel`] | The heading size (defaults to `3`)                                                                                                                                        |
+| component | `string`         | HTML element to render, e.g. &ldquo;h1&rdquo;, &ldquo;h2&rdquo;, etc.                                                                                                     |
+| children  | `string`         | Visible heading content, converted to slug (e.g. &ldquo;section-heading&rdquo;) to be used as hash link.<br/>Note: If the heading                                         |
+| label     | `string`         | Override the slug used as the hash link.<br/><br/>_Note: If the content of the heading is more than a simple string that can be slugified, then the `label` is required._ |
+
+[`HeadingLevel`]: https://seek-oss.github.io/braid-design-system/components/Heading
+[Braid Design System]: https://seek-oss.github.io/braid-design-system/

packages/docs-ui/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@braid-design-system/docs-ui",
+  "version": "0.0.0",
+  "license": "MIT",
+  "author": "SEEK",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "crackle dev --webpack",
+    "build": "crackle package",
+    "format:eslint": "eslint --cache --fix .",
+    "format:prettier": "prettier --cache --write .",
+    "lint:eslint": "eslint --cache .",
+    "lint:prettier": "prettier --cache --list-different .",
+    "lint:tsc": "tsc"
+  },
+  "dependencies": {
+    "@vanilla-extract/css": "^1.9.2"
+  },
+  "devDependencies": {
+    "braid-design-system": "*",
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "braid-design-system": "^32.0.0",
+    "react": "^18.2.0"
+  }
+}

packages/docs-ui/project.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://raw.githubusercontent.com/nrwl/nx/15.6.3/packages/nx/schemas/project-schema.json",
+  "namedInputs": {
+    "default": ["{projectRoot}/**/*"]
+  },
+  "targets": {
+    "build": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "build"
+      }
+    },
+    "lint": {},
+    "format": {}
+  }
+}

packages/docs-ui/src/components/LinkableHeading/LinkableHeading.css.ts

@@ -0,0 +1,10 @@
+import { style } from '@vanilla-extract/css';
+
+export const linkableHeading = style({});
+export const hashLink = style({
+  selectors: {
+    [`${linkableHeading}:hover &`]: {
+      opacity: 1,
+    },
+  },
+});

packages/docs-ui/src/components/LinkableHeading/LinkableHeading.tsx

@@ -0,0 +1,48 @@
+import React, { type ReactNode, type ComponentProps } from 'react';
+import { Heading, Box, IconLink, Link } from 'braid-design-system';
+import * as styles from './LinkableHeading.css';
+
+type HeadingProps = ComponentProps<typeof Heading>;
+
+type LinkableHeadingProps = {
+  level?: HeadingProps['level'];
+  component?: HeadingProps['component'];
+} & ({ children: string } | { children: ReactNode; label: string });
+
+const slugify = (string: string) =>
+  string
+    .replace(/[\s?]/g, '-')
+    .replace('--', '-')
+    .replace(/-$/, '')
+    .toLowerCase();
+
+export const LinkableHeading = ({
+  level = '3',
+  component,
+  ...restProps
+}: LinkableHeadingProps) => {
+  const label = 'label' in restProps ? restProps.label : restProps.children;
+  const slug = slugify(label);
+
+  return (
+    <Box display="flex">
+      <Box className={styles.linkableHeading} display="inlineBlock">
+        <Box id={slug} position="absolute" />
+        <Link href={`#${slug}`}>
+          <Heading level={level} component={component}>
+            {restProps.children}{' '}
+            <Box
+              component="span"
+              transition="fast"
+              marginLeft="xxsmall"
+              opacity={0}
+              className={styles.hashLink}
+            >
+              <IconLink />
+            </Box>
+          </Heading>
+        </Link>
+      </Box>
+    </Box>
+  );
+};

packages/docs-ui/src/index.ts

@@ -0,0 +1 @@
+export { LinkableHeading } from './components/LinkableHeading/LinkableHeading';

packages/docs-ui/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["./src"]
+}

site/project.json

@@ -9,7 +9,7 @@
       "executor": "nx:noop"
     },
     "start:site": {
-      "dependsOn": ["generate"],
+      "dependsOn": ["generate", "^dev"],
       "executor": "nx:run-script",
       "options": {
         "script": "start:site"