Merge branch 'main' into add-chromatic

.babelrc.json

@@ -0,0 +1,15 @@
+{
+  "sourceType": "unambiguous",
+  "presets": [
+    [
+      "@babel/preset-env",
+      {
+        "targets": {
+          "chrome": 100
+        }
+      }
+    ],
+    "@babel/preset-typescript"
+  ],
+  "plugins": []
+}

.github/FUNDING.yml

@@ -1,2 +0,0 @@
-github: just-the-docs
-open_collective: just-the-docs

.github/workflows/chromatic.yml

@@ -0,0 +1,51 @@
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+name: 'Chromatic'
+
+jobs:
+  chromatic:
+    name: "Chromatic"
+    strategy:
+      matrix:
+        jekyll-version: [4.3]
+        os: [ ubuntu-latest ]
+        ruby-version: [3.1]
+        node-version: [18.x]
+    runs-on: ${{ matrix.os }}
+    steps:
+
+    # Ruby setup
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    - name: Setup Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: false
+    - name: Bundle Install
+      run: bundle install
+    - name: Install Jekyll ${{ matrix.jekyll-version }}
+      run: gem install jekyll -v ${{ matrix.jekyll-version }}
+    - name: Init Search
+      run: bundle exec rake search:init
+    - name: Build Site
+      run: bundle exec jekyll build
+
+    # Node setup
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm install
+    - run: npm run build-storybook
+    - name: Publish to Chromatic
+      uses: chromaui/action@v1
+      env:
+        CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

.gitignore

@@ -16,10 +16,13 @@ vendor/
 
 # These next files are used by Just the Docs developers. They are not necessary for end users of the theme, only developers.
 
-# We use Stylelint and Prettier, JavaScript tools, to lint and format our own code.
+# We use Stylelint and Prettier, JavaScript tools, to lint and format our own code,
 # We use Node.js as our runtime, so we ignore node_modules
 node_modules
 
+# We also use Storybook to test regressions in changes; we ignore the build output.
+storybook-static
+
 # .DS_Store is a macOS-only metadata file about directories. Convention is to not commit them.
 # See: https://en.wikipedia.org/wiki/.DS_Store
 .DS_Store

.storybook/main.js

@@ -0,0 +1,17 @@
+/** @type { import('@storybook/html-webpack5').StorybookConfig } */
+const config = {
+  stories: ["../stories/**/*.mdx", "../stories/**/*.stories.@(js|jsx|ts|tsx)"],
+  addons: [
+    "@storybook/addon-links",
+    "@storybook/addon-essentials",
+    "@storybook/addon-interactions",
+  ],
+  framework: {
+    name: "@storybook/html-webpack5",
+    options: {},
+  },
+  docs: {
+    autodocs: "tag",
+  },
+}
+export default config

.storybook/preview.js

@@ -0,0 +1,14 @@
+/** @type { import('@storybook/html').Preview } */
+const preview = {
+  parameters: {
+    actions: { argTypesRegex: "^on[A-Z].*" },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/,
+      },
+    },
+  },
+}
+
+export default preview

CHANGELOG.md

@@ -17,18 +17,8 @@ This website is built from the `HEAD` of the `main` branch of the theme reposito
 
 Code changes to `main` that are *not* in the latest release:
 
-- N/A
-
-## Release v0.6.2
-
-Hi all, this is a small patch release that includes two changes: adding a missing Windows emoji font fallback, and removing some (now-unused) code introduced in 0.6.
-
-### Bugfixes
-
 - Fixed: Windows emoji font fallback by [@flanakin] in [#1337]
-- Removed: unused `.passive` toggle in navigation by [@pdmosses] in [#1335]
 
-[#1335]: https://github.com/just-the-docs/just-the-docs/pull/1335
 [#1337]: https://github.com/just-the-docs/just-the-docs/pull/1337
 
 ### New Contributors

_config.yml

@@ -48,6 +48,7 @@ exclude:
    - Dockerfile
  # theme test code
    - fixtures/
+   - stories/
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"

_includes/css/activation.scss.liquid

@@ -134,10 +134,11 @@
   }
 }
 
-// Styling for nav-list-expanders at first and second levels:
+// Styling for nav-list-expanders at first and second levels,
+// suppressed when a click has deactivated the expander (making the nav-list-item .passive):
 {{ activation_collection_prefix }} {
-  > .nav-list-item:nth-child({{ activation_first_level_index }}){%- if activation_second_level_index %},
-  > .nav-list-item:nth-child({{ activation_first_level_index }}) > .nav-list > .nav-list-item:nth-child({{ activation_second_level_index }}){% endif %} {
+  > .nav-list-item:not(.passive):nth-child({{ activation_first_level_index }}){%- if activation_second_level_index %},
+  > .nav-list-item:not(.passive):nth-child({{ activation_first_level_index }}) > .nav-list > .nav-list-item:not(.passive):nth-child({{ activation_second_level_index }}){% endif %} {
     > .nav-list-expander svg {
       @if $nav-list-expander-right {
         transform: rotate(-90deg);
@@ -153,7 +154,7 @@
 }
 
 // Styling for nav-list-expander for categories:
-.site-nav > .nav-category-list > .nav-list-item {
+.site-nav > .nav-category-list > .nav-list-item:not(.passive) {
   > .nav-list-expander svg {
     @if $nav-list-expander-right {
       transform: rotate(-90deg);

_sass/buttons.scss

@@ -105,7 +105,7 @@
 }
 
 .btn-purple {
-  @include btn-color($white, $purple-100);
+  @include btn-color($white, $purple-300);
 }
 
 .btn-blue {

assets/js/just-the-docs.js

@@ -31,7 +31,10 @@ function initNav() {
     }
     if (target) {
       e.preventDefault();
-      target.ariaPressed = target.parentNode.classList.toggle('active');
+      const active = target.parentNode.classList.toggle('active');
+      const passive = target.parentNode.classList.toggle('passive');
+      if (active && passive) target.parentNode.classList.toggle('passive');
+      target.ariaPressed = active;
     }
   });
 
@@ -495,7 +498,8 @@ function scrollNav() {
 }
 
 // Find the nav-list-link that refers to the current page
-// then make it and all enclosing nav-list-item elements active.
+// then make it and all enclosing nav-list-item elements active,
+// and make all other folded collections passive
 
 function activateNav() {
   var target = navLink();
@@ -511,6 +515,17 @@ function activateNav() {
       target = target.parentNode;
     }
   }
+  const elements = document.getElementsByClassName("nav-category-list");
+  for (const element of elements) {
+    const item = element.children[0];
+    const active = item.classList.toggle('active');
+    if (active) {
+      item.classList.toggle('active', false);
+      item.classList.toggle('passive', true);
+    } else {
+      item.classList.toggle('active', true);
+    }
+  }
 }
 
 // Document ready

docs/customization.md

@@ -52,7 +52,7 @@ New (v0.4.2)
 {: .label .label-green }
 
 
-In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme.
+In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who are want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme.
 
 ## Custom schemes
 

docs/navigation-structure.md

@@ -20,7 +20,7 @@ nav_order: 5
 
 ## Main navigation
 
-The main navigation for your Just the Docs site is on the left side of the page on large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).
+The main navigation for your Just the Docs site is on the left side of the page at large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).
 
 By default, all pages will appear as top level pages in the main nav unless a parent page is defined (see [Pages with Children](#pages-with-children)).
 
@@ -300,7 +300,7 @@ This example skips the page name heading (`#`) from the TOC, as well as the head
 
 ### Collapsible Table of Contents
 
-The Table of Contents can be made collapsible using the `<details>` and `<summary>` elements, as in the following example. The attribute `open` (expands the Table of Contents by default) and the styling with `{: .text-delta }` are optional.
+The Table of Contents can be made collapsible using the `<details>` and `<summary>` elements , as in the following example. The attribute `open` (expands the Table of Contents by default) and the styling with `{: .text-delta }` are optional.
 
 ```markdown
 <details open markdown="block">

docs/utilities/layout.md

@@ -61,7 +61,7 @@ Use `mx-auto` to horizontally center elements.
 In Markdown, use the `{: }` wrapper to apply custom classes:
 
 ```markdown
-This paragraph will have a margin bottom of 1rem/16px on large screens.
+This paragraph will have a margin bottom of 1rem/16px at large screens.
 {: .mb-lg-4 }
 
 This paragraph will have 2rem/32px of padding on the right and left at all screen sizes.

docs/utilities/utilities.md

@@ -9,5 +9,5 @@ permalink: docs/utilities
 # Utilities
 {: .no_toc }
 
-CSS utility classes come in handy when you want to override default styles to create additional whitespace (margins/padding), correct unexpected shifts in font size or weight, add color, or hide (or show) something at a specific screen size.
+CSS utility classes come in handy when you to want to override default styles to create additional whitespace (margins/padding), correct unexpected shifts in font size or weight, add color, or hide (or show) something at a specific screen size.
 {: .fs-6 .fw-300 }

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.6.2"
+  spec.version       = "0.6.1"
   spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
   spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]
 

package.json

@@ -1,22 +1,43 @@
 {
   "name": "just-the-docs",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "A modern Jekyll theme for documentation",
-  "repository": "just-the-docs/just-the-docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/just-the-docs/just-the-docs.git"
+  },
   "license": "MIT",
-  "bugs": "https://github.com/just-the-docs/just-the-docs/issues",
+  "bugs": {
+    "url": "https://github.com/just-the-docs/just-the-docs/issues"
+  },
   "devDependencies": {
+    "@babel/preset-env": "^7.21.4",
+    "@babel/preset-typescript": "^7.21.4",
+    "@storybook/addon-essentials": "^7.0.7",
+    "@storybook/addon-interactions": "^7.0.7",
+    "@storybook/addon-links": "^7.0.7",
+    "@storybook/blocks": "^7.0.7",
+    "@storybook/html": "^7.0.7",
+    "@storybook/html-webpack5": "^7.0.7",
+    "@storybook/testing-library": "^0.0.14-next.2",
+    "chromatic": "^6.17.3",
     "npm-run-all": "^4.1.5",
     "prettier": "^3.0.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "storybook": "^7.0.7",
     "stylelint": "^15.10.3",
-    "stylelint-config-standard-scss": "^11.0.0"
+    "stylelint-config-standard-scss": "^10.0.0"
   },
   "scripts": {
     "lint": "npm-run-all --parallel --continue-on-error lint:*",
     "lint:css": "stylelint '**/*.scss'",
     "lint:formatting": "prettier --check '**/*.{scss,js,json}'",
     "format": "prettier --write '**/*.{scss,js,json}'",
-    "test": "npm run lint"
+    "test": "npm run lint",
+    "storybook": "bundle exec jekyll build && storybook dev -p 6006",
+    "build-storybook": "bundle exec jekyll build && storybook build",
+    "chromatic": "npx chromatic --project-token=9355f489c51b -d storybook-static"
   },
   "stylelint": {
     "ignoreFiles": [
@@ -43,5 +64,7 @@
     "singleQuote": false,
     "tabWidth": 2,
     "trailingComma": "es5"
-  }
+  },
+  "homepage": "https://just-the-docs.com",
+  "_id": "just-the-docs@0.5.0"
 }

stories/Introduction.mdx

@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Example/Introduction" />
+
+# Storybook for Just the Docs
+
+A WIP [Storybook](https://storybook.js.org/) for Just the Docs.

stories/ui-components/Button.js

@@ -0,0 +1,11 @@
+import "../../_site/assets/css/just-the-docs-default.css"
+
+export const createButton = ({ variant = "default", label, size = "4" }) => {
+  const btn = document.createElement("button")
+  btn.type = "button"
+  btn.innerText = label
+
+  btn.className = ["btn", `btn-${variant}`, `fs-${size}`].join(" ")
+
+  return btn
+}

stories/ui-components/Button.stories.js

@@ -0,0 +1,68 @@
+import { createButton } from "./Button"
+
+export default {
+  title: "UI Components/Button",
+  tags: ["autodocs"],
+  render: ({ label, ...args }) => {
+    return createButton({ label, ...args })
+  },
+  argTypes: {
+    label: { control: "text" },
+    size: {
+      control: { type: "select" },
+      options: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["default", "primary", "purple", "blue", "green", "outline"],
+    },
+  },
+}
+
+export const Default = {
+  args: {
+    variant: "default",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Primary = {
+  args: {
+    variant: "primary",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Purple = {
+  args: {
+    variant: "purple",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Blue = {
+  args: {
+    variant: "blue",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Green = {
+  args: {
+    variant: "green",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Outline = {
+  args: {
+    variant: "outline",
+    label: "Button",
+    size: 4,
+  },
+}

stories/ui-components/Label.js

@@ -0,0 +1,10 @@
+import "../../_site/assets/css/just-the-docs-default.css"
+
+export const createLabel = ({ variant = "default", label, size = "4" }) => {
+  const btn = document.createElement("span")
+  btn.innerText = label
+
+  btn.className = ["label", `label-${variant}`, `fs-${size}`].join(" ")
+
+  return btn
+}

stories/ui-components/Label.stories.js

@@ -0,0 +1,68 @@
+import { createLabel } from "./Label"
+
+export default {
+  title: "UI Components/Label",
+  tags: ["autodocs"],
+  render: ({ label, ...args }) => {
+    return createLabel({ label, ...args })
+  },
+  argTypes: {
+    label: { control: "text" },
+    size: {
+      control: { type: "select" },
+      options: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["default", "purple", "blue", "green", "red", "yellow"],
+    },
+  },
+}
+
+export const Default = {
+  args: {
+    variant: "default",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Purple = {
+  args: {
+    variant: "purple",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Blue = {
+  args: {
+    variant: "blue",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Green = {
+  args: {
+    variant: "green",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Red = {
+  args: {
+    variant: "red",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Yellow = {
+  args: {
+    variant: "yellow",
+    label: "Label",
+    size: 4,
+  },
+}