@chassis-ui/docs 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @chassis-ui/docs
 
+## 0.7.0
+
+### Minor Changes
+
+- **Breaking.** The package needs `@chassis-ui/css` 0.6.0 or later: the peer range is `>=0.6.0`, it was `^0.5.0-0`. The layouts use the CSS grid of css 0.6, `.grid` with `col-span-*`, in place of the flexbox grid, `.row` with `.col-*`, which css 0.6 deprecates and css 0.7 removes. The header of `SingleLayout`, the sections list of `DocsLayout`, the footer and the lists of the header are grids. `NavLink` no longer sets a width: the lists of the header are two columns below `lg` by themselves. The loading rows of the search use the fraction widths, `w-4/12`. `.cxd-gutter` sets `--cx-container-padding` in place of `--cx-gutter-x`, with the same page margin of 1rem. The pages look as before, except that the footer columns are separated by the gutter of the breakpoint and move by a few pixels. See [UPGRADING.md](https://github.com/chassis-ui/website/blob/main/packages/docs/UPGRADING.md#from-06-to-07) for the classes to replace in a site's own pages.
+
 ## 0.6.3
 
 ### Patch Changes

package/README.md

@@ -23,7 +23,7 @@ pnpm add @chassis-ui/docs
 ```json
 {
   "@astrojs/markdown-remark": "^7.0.0",
-  "@chassis-ui/css": "^0.5.0-0",
+  "@chassis-ui/css": ">=0.6.0",
   "@pagefind/component-ui": "^1.0.0",
   "@shikijs/transformers": "^4.3.1",
   "astro": "^7.0.0",
@@ -376,6 +376,7 @@ The integration provides five modules: `virtual:chassis-docs/config`, `virtual:c
 
 | `@chassis-ui/docs` | Requires Astro             | Requires `@chassis-ui/css` | Requires Node | Built with                           |
 | ------------------ | -------------------------- | -------------------------- | ------------- | ------------------------------------ |
+| 0.7.0              | `^7.0.0`                   | `>=0.6.0`                  | `>=22.12.0`   | Astro 7.3.5, css 0.6.0, tokens 0.6.0 |
 | 0.6.3              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
 | 0.6.2              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |
 | 0.6.1              | `^7.0.0`                   | `^0.5.0-0`                 | `>=22.12.0`   | Astro 7.3.5, css 0.5.2, tokens 0.6.0 |

package/UPGRADING.md

@@ -1,5 +1,69 @@
 # Upgrading @chassis-ui/docs
 
+## From 0.6 to 0.7
+
+0.7.0 needs `@chassis-ui/css` 0.6.0 or later. The layouts use the CSS grid of that version,
+`.grid` with `col-span-*`, in place of the flexbox grid, `.row` with `.col-*`. css 0.6
+deprecates the flexbox grid and css 0.7 removes it.
+
+### 1. Update the dependencies
+
+```sh
+pnpm add -D @chassis-ui/docs@^0.7.0 @chassis-ui/css@^0.6.0
+```
+
+css 0.6.0 has changes of its own. Read its
+[changelog](https://github.com/chassis-ui/css/blob/main/packages/css/CHANGELOG.md) first:
+among them, the default gap of `.grid` is now the gutter token of the breakpoint.
+
+### 2. Move your own pages off the flexbox grid
+
+css 0.6 still has the flexbox grid, so the site builds and looks as before without this
+step. css 0.7 removes it. Replace the classes in your own components, pages and content:
+
+| Flexbox grid                             | CSS grid                                           |
+| ---------------------------------------- | -------------------------------------------------- |
+| `row`                                    | `grid`                                             |
+| `col-6`, `md:col-6`                      | `col-span-6`, `col-span-full md:col-span-6`        |
+| `col-12`                                 | `col-span-full`                                    |
+| `row row-cols-1 md:row-cols-3` and `col` | `grid grid-cols-1 md:grid-cols-3`, no class inside |
+| `offset-1`                               | `col-start-2`                                      |
+| `col lg:col-10 mx-auto`                  | `col-span-full lg:col-span-10 lg:col-start-2`      |
+| `g-md`, `gx-md`, `gy-md`                 | `gap-md`, `column-gap-md`, `row-gap-md`            |
+| `col-auto`                               | `d-flex` with `gap-*` on the parent                |
+| `col-6` outside a `row`                  | `w-6/12`                                           |
+| `col` outside a `row`                    | `flex-fill`                                        |
+
+- An item without a span is one column wide. A column that was full width below its
+  breakpoint, such as `md:col-6`, needs `col-span-full` too.
+- A `row` without a gutter class had a gutter of 1.5rem between columns and none between
+  rows. A `grid` has the gutter of the breakpoint in both directions, from 0.5rem to 3rem.
+  Add `row-gap-0` where the items have margins of their own.
+- A grid beside the sidebar, or in a card, is narrower than the viewport that the gutter
+  follows. Give it a `gap-*` class, and `grid-cols-{n}` in place of twelve columns.
+- An auto margin shrinks a grid item to its content. Center an item with `col-start-*`.
+
+The [grid page](https://chassis-ui.com/css/docs/layout/grid/) of Chassis CSS has the full
+table.
+
+### What changes in the package
+
+- **`NavLink` sets no width.** Its item was `nav-item col-6 lg:col-auto`, half of the list
+  below `lg`. It is `nav-item` now, and the lists of the header are a grid of two columns
+  below `lg`. A list of your own that relied on the two columns takes
+  `d-grid grid-cols-2 lg:d-flex`.
+- **`.cxd-gutter` sets `--cx-container-padding`.** It set `--cx-gutter-x`, which the
+  container stops reading in css 0.7. The page margin of the docs layout is 1rem, as
+  before. A rule of your own that set `--cx-gutter-x` on that element sets
+  `--cx-container-padding` to half of it.
+- **The footer and the header of `SingleLayout` take the gutter of the breakpoint.** The
+  footer columns move by a few pixels, 20 at most on the widest screens.
+
+### Check the result
+
+Build the site before and after the upgrade and compare the pages in a browser, at a phone
+width and a desktop width. Apart from the footer columns, nothing of the package moves.
+
 ## From 0.5 to 0.6
 
 0.6.0 is a breaking release. In 0.5 a site had to supply five modules behind a `@libs/*`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -70,7 +70,7 @@
   },
   "peerDependencies": {
     "@astrojs/markdown-remark": "^7.0.0",
-    "@chassis-ui/css": "^0.5.0-0",
+    "@chassis-ui/css": ">=0.6.0",
     "@pagefind/component-ui": "^1.0.0",
     "@shikijs/transformers": "^4.3.1",
     "astro": "^7.0.0",
@@ -106,8 +106,16 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
+    "@astrojs/markdown-remark": "^7.3.1",
+    "@chassis-ui/css": "^0.6.0",
+    "@pagefind/component-ui": "^1.5.2",
+    "@shikijs/transformers": "^4.5.0",
     "astro": "^7.3.5",
+    "html-validate": "^11.16.1",
+    "rehype-autolink-headings": "^7.1.0",
     "remark-mdx": "^3.1.1",
-    "vfile": "^6.0.3"
+    "sass": "^1.105.1",
+    "vfile": "^6.0.3",
+    "vnu-jar": "^26.10.2"
   }
 }

package/src/components/NavLink.astro

@@ -21,7 +21,7 @@ interface Props {
 const { active, class: className, ...props } = Astro.props
 ---
 
-<li class="nav-item col-6 lg:col-auto">
+<li class="nav-item">
   <a
     aria-current={active ? true : undefined}
     class:list={['nav-link', className, { active }]}

package/src/js/search.js

@@ -472,8 +472,8 @@ class CxdSearchResults extends HTMLElement {
             <div class="icon cxd-search-icon skeleton">
             </div>
             <div class="cxd-search-item-body">
-              <div class="skeleton col-4"></div>
-              <div class="skeleton col-12"></div>
+              <div class="skeleton w-4/12"></div>
+              <div class="skeleton w-100"></div>
             </div>
           </div>
         `

package/src/layouts/DocsLayout.astro

@@ -146,9 +146,9 @@ if (frontmatter.toc) {
       <div class="cxd-content">
         {
           frontmatter.sections && (
-            <div class="row g-xl">
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-xl">
               {frontmatter.sections.map((section: DocSection) => (
-                <div class="md:col-6">
+                <div>
                   <a
                     class="d-block text-decoration-none"
                     href={getDocsPath(

package/src/layouts/SingleLayout.astro

@@ -24,8 +24,8 @@ mainProps['class'] = 'min-vh-100'
 <BaseLayout {...Astro.props} layout="single" overrides={{ main: mainProps }}>
   <header class="py-xl md:py-3xl border-bottom border-subtle">
     <div class="container 2xl">
-      <div class="row">
-        <div class="col lg:col-10 2xl:col-8">
+      <div class="grid">
+        <div class="col-span-full lg:col-span-10 2xl:col-span-8">
           <h1 class="mt-0">{title}</h1>
           <p class="font-lead">{description}</p>
           <slot name="header-content" />

package/src/layouts/footer/Footer.astro

@@ -10,8 +10,8 @@ import { getStaticPath } from '../../site'
 
 <footer class="cxd-footer py-6xl">
   <div class="container 2xl fg-subtle">
-    <div class="row">
-      <div class="md:col-10 lg:col-5 mb-md">
+    <div class="grid row-gap-0">
+      <div class="col-span-full md:col-span-10 lg:col-span-5 mb-md">
         <a
           class="d-inline-flex align-items-center mb-xs text-body-emphasis text-decoration-none"
           href="/"
@@ -30,7 +30,7 @@ import { getStaticPath } from '../../site'
           >
         </p>
       </div>
-      <div class="sm:col-4 lg:col-2 lg:offset-1 mb-md">
+      <div class="col-span-full sm:col-span-4 lg:col-span-2 lg:col-start-7 mb-md">
         <p class="h6 mb-xs">Docs</p>
         <ul class="nav">
           <li><a href="/tokens">Design Tokens</a></li>
@@ -41,7 +41,7 @@ import { getStaticPath } from '../../site'
           <li><a href="/icons">Icon Generator</a></li>
         </ul>
       </div>
-      <div class="sm:col-4 lg:col-2 mb-md">
+      <div class="col-span-full sm:col-span-4 lg:col-span-2 mb-md">
         <p class="h6 mb-xs">Github</p>
         <ul class="nav">
           <li><a href="https://github.com/chassis-ui/tokens">Chassis Tokens</a></li>
@@ -52,7 +52,7 @@ import { getStaticPath } from '../../site'
           <li><a href="https://github.com/chassis-ui/icons">Chassis Icons</a></li>
         </ul>
       </div>
-      <div class="sm:col-4 lg:col-2 mb-md">
+      <div class="col-span-full sm:col-span-4 lg:col-span-2 mb-md">
         <p class="h6 mb-xs">Project</p>
         <ul class="nav">
           <li><a href="/about">About</a></li>

package/src/layouts/header/Navigation.astro

@@ -90,14 +90,16 @@ const isActive = (path: string) => {
 
       <hr class="lg:d-none m-0" />
       <div class="drawer-body lg:p-0">
-        <ul class="navbar-nav flex-row flex-wrap cxd-navbar-nav mx-0 lg:mx-md">
+        <ul
+          class="navbar-nav d-grid grid-cols-2 lg:d-flex flex-row flex-wrap cxd-navbar-nav mx-0 lg:mx-md"
+        >
           <NavLink active={isActive('/tokens')} href="/tokens">Tokens</NavLink>
           <NavLink active={isActive('/figma')} href="/figma">Figma</NavLink>
           <NavLink active={isActive('/css')} href="/css">CSS</NavLink>
           <NavLink active={isActive('/react')} href="/react">React</NavLink>
           <NavLink active={isActive('/assets')} href="/assets">Assets</NavLink>
           <NavLink active={isActive('/icons')} href="/icons">Icons</NavLink>
-          <li class="nav-item col-12 lg:col-auto lg:d-flex">
+          <li class="nav-item col-span-full lg:d-flex">
             <div class="vr d-none lg:d-flex my-auto lg:mx-sm"></div>
             <hr class="lg:d-none" />
           </li>
@@ -107,7 +109,9 @@ const isActive = (path: string) => {
 
         <hr class="lg:d-none m-0" />
 
-        <ul class="navbar-nav flex-row flex-wrap lg:ms-auto align-items-center">
+        <ul
+          class="navbar-nav d-grid grid-cols-2 lg:d-flex flex-row flex-wrap lg:ms-auto align-items-center"
+        >
           {
             figmaHandle && (
               <NavLink
@@ -134,7 +138,7 @@ const isActive = (path: string) => {
               </NavLink>
             )
           }
-          <li class="nav-item col-12 lg:col-auto">
+          <li class="nav-item col-span-full">
             <div class="vr d-none lg:d-flex h-100 lg:mx-2xs"></div>
             <hr class="lg:d-none" />
           </li>

package/src/scss/_layout.scss

@@ -3,7 +3,7 @@
 
 @layer custom {
   .cxd-gutter {
-    --cx-gutter-x: #{$cxd-gutter-x};
+    --cx-container-padding: #{$cxd-gutter-x * .5};
   }
 
   .cxd-layout {