docpensieve 0.1.2 → 0.1.4

package/starter/02-components/01-card.mdx

@@ -7,19 +7,22 @@ description: Structured card, with header, body, footer and image.
 
 ## The simplest
 
-<Card className="max-w-sm">
+<Card style={{ maxWidth: '24rem' }}>
   <CardBody>A card reduced to its body.</CardBody>
 </Card>
 
 ```mdx
-<Card className="max-w-sm">
+<Card>
   <CardBody>A card reduced to its body.</CardBody>
 </Card>
 ```
 
+The examples of this page narrow some cards through `style`, which every theme
+understands; the look proper comes further down.
+
 ## With its three parts
 
-<Card className="max-w-sm">
+<Card style={{ maxWidth: '24rem' }}>
   <CardHeader>Header</CardHeader>
   <CardBody>
     The body of the card. It takes the remaining space when several cards sit side by side.
@@ -62,7 +65,12 @@ meaning deserves a written `alt`.
 
 ## A grid of cards
 
-It is the most common use. `h-full` aligns the heights whatever the content.
+It is the most common use. Stretching each card to the height of its column
+aligns them whatever the content.
+
+<ForTheme framework="tailwind">
+
+With the Tailwind theme, the `h-full` utility does it:
 
 <Columns>
   <Column>
@@ -97,9 +105,56 @@ It is the most common use. `h-full` aligns the heights whatever the content.
 </Columns>
 ```
 
+</ForTheme>
+<ForTheme framework="custom">
+
+With the custom theme, a class of your own does it — here `full-height`, from
+`theme/99-docpensieve.css`:
+
+<Columns>
+  <Column>
+    <Card className="full-height">
+      <CardHeader>Stateless</CardHeader>
+      <CardBody>
+        Components are rendered at build time. None of them keeps state or listens to events.
+      </CardBody>
+    </Card>
+  </Column>
+  <Column>
+    <Card className="full-height">
+      <CardHeader>Dependency-free</CardHeader>
+      <CardBody>The delivered HTML loads nothing.</CardBody>
+    </Card>
+  </Column>
+  <Column>
+    <Card className="full-height">
+      <CardHeader>No surprises</CardHeader>
+      <CardBody>
+        What cannot be rendered stops the build rather than disappearing silently.
+      </CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+```mdx
+<Columns>
+  <Column>
+    <Card className="full-height">…</Card>
+  </Column>
+</Columns>
+```
+
+```css
+.full-height {
+  block-size: 100%;
+}
+```
+
+</ForTheme>
+
 ## Elevation
 
-<Card className="max-w-sm" elevated>
+<Card style={{ maxWidth: '24rem' }} elevated>
   <CardBody>This card carries a shadow.</CardBody>
 </Card>
 
@@ -109,7 +164,7 @@ It is the most common use. `h-full` aligns the heights whatever the content.
 
 ## Fully clickable
 
-<Card className="max-w-sm" href="./columns/">
+<Card style={{ maxWidth: '24rem' }} href="./columns/">
   <CardHeader>Go to the columns</CardHeader>
   <CardBody>The whole card is a link, not just the title.</CardBody>
 </Card>
@@ -126,6 +181,8 @@ root — the same rules as for a Markdown link.
 Nothing specific to the component: a card, a little typography, and the footer
 carrying the caption.
 
+<ForTheme framework="tailwind">
+
 <Columns>
   <Column span={4}>
     <Card className="h-full text-center">
@@ -139,7 +196,7 @@ carrying the caption.
   <Column span={4}>
     <Card className="h-full text-center">
       <CardBody>
-        <div className="text-4xl font-semibold text-indigo-600">8</div>
+        <div className="text-4xl font-semibold text-indigo-600">9</div>
         <div className="text-sm">components</div>
       </CardBody>
       <CardFooter>usable without an import</CardFooter>
@@ -156,8 +213,45 @@ carrying the caption.
   </Column>
 </Columns>
 
+</ForTheme>
+<ForTheme framework="custom">
+
+<Columns>
+  <Column span={4}>
+    <Card className="full-height centered">
+      <CardBody>
+        <div className="figure">0</div>
+        <div className="small">bytes of JavaScript</div>
+      </CardBody>
+      <CardFooter>on every delivered page</CardFooter>
+    </Card>
+  </Column>
+  <Column span={4}>
+    <Card className="full-height centered">
+      <CardBody>
+        <div className="figure">9</div>
+        <div className="small">components</div>
+      </CardBody>
+      <CardFooter>usable without an import</CardFooter>
+    </Card>
+  </Column>
+  <Column span={4}>
+    <Card className="full-height centered">
+      <CardBody>
+        <div className="figure">1</div>
+        <div className="small">stylesheet</div>
+      </CardBody>
+      <CardFooter>per version</CardFooter>
+    </Card>
+  </Column>
+</Columns>
+
+</ForTheme>
+
 ## A warning card
 
+<ForTheme framework="tailwind">
+
 <Card className="border-amber-400 bg-amber-50 dark:bg-amber-950/30">
   <CardHeader className="text-amber-800 dark:text-amber-200">To check before publishing</CardHeader>
   <CardBody className="text-sm">
@@ -166,8 +260,23 @@ carrying the caption.
   </CardBody>
 </Card>
 
+</ForTheme>
+<ForTheme framework="custom">
+
+<Card className="warning">
+  <CardHeader className="warning-title">To check before publishing</CardHeader>
+  <CardBody className="small">
+    A generated site can compile without error and contain dead links.
+    <code>docpensieve check</code> reads the output back.
+  </CardBody>
+</Card>
+
+</ForTheme>
+
 ## The look through className
 
+<ForTheme framework="tailwind">
+
 The component offers no typography prop: the theme's utilities take care of
 it, and win over the default style.
 
@@ -193,3 +302,42 @@ The component rules live in the `components` layer, below the utilities: a
 <Card className="max-w-sm border-0 shadow-none bg-transparent">
   <CardBody className="px-0">No border, no background, no inner padding.</CardBody>
 </Card>
+
+</ForTheme>
+<ForTheme framework="custom">
+
+The component offers no typography prop: the look comes from classes of your
+own, written in the `theme/` folder — here those of `theme/99-docpensieve.css`.
+
+<Card className="narrow highlight">
+  <CardHeader className="centered caps accent-text">Centred, in capitals</CardHeader>
+  <CardBody className="small italic">Small, italic body.</CardBody>
+</Card>
+
+```mdx
+<Card className="highlight">
+  <CardHeader className="centered caps accent-text">Centred, in capitals</CardHeader>
+  <CardBody className="small italic">Small, italic body.</CardBody>
+</Card>
+```
+
+```css
+.highlight {
+  border-color: var(--dp-accent);
+  background: var(--dp-accent-soft);
+}
+
+.caps {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+```
+
+The component rules live in the `components` layer, those of the theme folder
+in none: a class of yours always wins, even to undo the default style.
+
+<Card className="narrow plain">
+  <CardBody className="flush">No border, no background, no inner padding.</CardBody>
+</Card>
+
+</ForTheme>

package/starter/02-components/02-columns.mdx

@@ -81,6 +81,10 @@ produce nothing visible, and the error would take a long time to find.
 independent settings. The grid subtracts the gaps by itself, so spacing the
 columns distorts no width.
 
+<ForTheme framework="tailwind">
+
+With the Tailwind theme, a `gap-*` utility sets it:
+
 <Columns className="gap-10">
   <Column>
     <Card>
@@ -98,6 +102,37 @@ columns distorts no width.
 <Columns className="gap-10">…</Columns>
 ```
 
+</ForTheme>
+<ForTheme framework="custom">
+
+With the custom theme, a class of your own sets it — here `wide-gap`, from
+`theme/99-docpensieve.css`:
+
+<Columns className="wide-gap">
+  <Column>
+    <Card>
+      <CardBody>The gap widens</CardBody>
+    </Card>
+  </Column>
+  <Column>
+    <Card>
+      <CardBody>without touching the widths</CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+```mdx
+<Columns className="wide-gap">…</Columns>
+```
+
+```css
+.wide-gap {
+  gap: 2.5rem;
+}
+```
+
+</ForTheme>
+
 ## An aside next to the text
 
 The most useful layout in documentation: the main point wide, the remark
@@ -115,9 +150,15 @@ class table is announced to them.
 
   </Column>
   <Column span={4}>
-    <Card className="h-full border-indigo-400 bg-indigo-50 dark:bg-indigo-950/30">
-      <CardHeader className="text-sm">Remember</CardHeader>
-      <CardBody className="text-sm">
+    <Card
+      style={{
+        height: '100%',
+        borderColor: 'var(--dp-accent)',
+        background: 'var(--dp-accent-soft)',
+      }}
+    >
+      <CardHeader style={{ fontSize: '0.875rem' }}>Remember</CardHeader>
+      <CardBody style={{ fontSize: '0.875rem' }}>
         A component that produces a URL resolves it itself, following the same rules as a
         Markdown link.
       </CardBody>
@@ -159,8 +200,12 @@ versions: [
 ## Letting content flow
 
 For a text or a gallery that _flows_ from one column to the next, the grid is
-not the right tool and no component is needed: the theme's utilities are
-enough, directly in the page.
+not the right tool and no component is needed: CSS multi-column is enough,
+directly in the page.
+
+<ForTheme framework="tailwind">
+
+With the Tailwind theme, its utilities write it:
 
 <div className="columns-2 gap-6 sm:columns-3">
   <Card className="mb-6 break-inside-avoid">
@@ -184,6 +229,54 @@ enough, directly in the page.
 <div className="columns-2 gap-6 sm:columns-3">…</div>
 ```
 
+</ForTheme>
+<ForTheme framework="custom">
+
+With the custom theme, a class of your own — here `flow`, from
+`theme/99-docpensieve.css`:
+
+<div className="flow">
+  <Card>
+    <CardBody>One</CardBody>
+  </Card>
+  <Card>
+    <CardBody>Two, a little longer, so that the heights differ.</CardBody>
+  </Card>
+  <Card>
+    <CardBody>Three</CardBody>
+  </Card>
+  <Card>
+    <CardBody>Four</CardBody>
+  </Card>
+  <Card>
+    <CardBody>Five</CardBody>
+  </Card>
+</div>
+
+```mdx
+<div className="flow">…</div>
+```
+
+```css
+.flow {
+  columns: 2;
+  column-gap: 1.5rem;
+}
+
+@media (min-width: 40rem) {
+  .flow {
+    columns: 3;
+  }
+}
+
+.flow > * {
+  break-inside: avoid;
+  margin-block-end: 1.5rem;
+}
+```
+
+</ForTheme>
+
 The difference is there: above, the order is vertical and the browser
 distributes as it likes; with `Columns`, each block stays where you put it.
 

package/starter/02-components/03-time-timer.mdx

@@ -93,7 +93,7 @@ months.
 
 An announcement banner that removes itself:
 
-<Card className="border-indigo-400 bg-indigo-50 dark:bg-indigo-950/30">
+<Card style={{ borderColor: 'var(--dp-accent)', background: 'var(--dp-accent-soft)' }}>
   <CardBody>
     <TimeTimer start="01/01/2020" duration="36500d">
       **Version 1.1 in preparation.** New features are written in this version.

package/starter/02-components/05-tree.mdx

@@ -46,7 +46,7 @@ children** is a collapsible branch, an entry **without children** is a leaf.
 
 <Columns>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardHeader>Closed by default</CardHeader>
       <CardBody>
         <Tree>
@@ -58,7 +58,7 @@ children** is a collapsible branch, an entry **without children** is a leaf.
     </Card>
   </Column>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardHeader>Opened by `open`</CardHeader>
       <CardBody>
         <Tree>
@@ -146,12 +146,42 @@ well.
 
 ## Styling the tree
 
+<ForTheme framework="tailwind">
+
 <Tree className="text-indigo-700 dark:text-indigo-300">
   <TreeItem label="in colour" open>
     <TreeItem label="the children inherit" />
   </TreeItem>
 </Tree>
 
+```mdx
+<Tree className="text-indigo-700 dark:text-indigo-300">…</Tree>
+```
+
+</ForTheme>
+<ForTheme framework="custom">
+
+A class of your own colours it — here `accent-text`, from
+`theme/99-docpensieve.css`, which follows the palette in dark mode too:
+
+<Tree className="accent-text">
+  <TreeItem label="in colour" open>
+    <TreeItem label="the children inherit" />
+  </TreeItem>
+</Tree>
+
+```mdx
+<Tree className="accent-text">…</Tree>
+```
+
+```css
+.accent-text {
+  color: var(--dp-accent);
+}
+```
+
+</ForTheme>
+
 ## What it does not announce
 
 The structure is a nested list, not a `role="tree"`. That role promises a

package/starter/02-components/06-scroll-to-top.mdx

@@ -31,6 +31,8 @@ scrollToTop: false,
 text**, with its own content — a pointer at the end of a chapter, for
 instance.
 
+<ForTheme framework="tailwind">
+
 <div className="flex flex-wrap items-center gap-3">
   <ScrollToTop className="!static !inline-flex !w-auto !shadow-none px-4" label="Top of page">
     Top
@@ -59,6 +61,44 @@ All three carry `!static`: that is what takes them out of the corner of the
 screen to set them in the text. **Without this class, they would stack** on
 top of the shell's button, all in the same place.
 
+</ForTheme>
+<ForTheme framework="custom">
+
+<div className="row">
+  <ScrollToTop className="inline-button" label="Top of page">
+    Top
+  </ScrollToTop>
+  <ScrollToTop className="inline-button" label="Back to the summit">
+    ↑ Summit
+  </ScrollToTop>
+  <ScrollToTop className="inline-button accent-text" label="Start reading again">
+    Start again
+  </ScrollToTop>
+</div>
+
+```mdx
+<ScrollToTop className="inline-button" label="Top of page">
+  Top
+</ScrollToTop>
+```
+
+```css
+.inline-button {
+  position: static;
+  display: inline-flex;
+  inline-size: auto;
+  box-shadow: none;
+  padding-inline: 1rem;
+}
+```
+
+All three carry `inline-button`, from `theme/99-docpensieve.css`: its
+`position: static` takes them out of the corner of the screen to set them in
+the text. **Without this class, they would stack** on top of the shell's
+button, all in the same place.
+
+</ForTheme>
+
 The accessible name stays set by `label`: without it, the link would announce
 itself by its appearance alone.
 

package/starter/02-components/07-skill.mdx

@@ -31,7 +31,7 @@ Content passed as a child becomes a comment under the bar.
 `shape="circle"` draws a dial rather than a bar. Useful when the gauges are
 few and you want them to stand out.
 
-<div className="flex flex-wrap">
+<div style={{ display: 'flex', flexWrap: 'wrap' }}>
   <Skill name="Accessibility" level={85} shape="circle" />
   <Skill name="Performance" level={92} shape="circle" />
   <Skill name="Coverage" level={64} shape="circle" />
@@ -53,7 +53,9 @@ the entry animation only has to start from zero.
 
 It is set through `--dp-skill-size`, on the gauge or on what surrounds it.
 
-<div className="flex flex-wrap items-end" style={{ '--dp-skill-size': '4rem' }}>
+<div
+  style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'flex-end', '--dp-skill-size': '4rem' }}
+>
   <Skill name="Smaller" level={70} shape="circle" />
   <Skill name="Also smaller" level={45} shape="circle" />
 </div>
@@ -72,7 +74,7 @@ It is set through `--dp-skill-size`, on the gauge or on what surrounds it.
 
 ### Without the figure
 
-<div className="flex flex-wrap">
+<div style={{ display: 'flex', flexWrap: 'wrap' }}>
   <Skill name="Silent" level={55} shape="circle" showValue={false} />
 </div>
 
@@ -96,7 +98,7 @@ seeing them match helps read a column of gauges at a glance.
 
 ### As a circle too
 
-<div className="flex flex-wrap">
+<div style={{ display: 'flex', flexWrap: 'wrap' }}>
   <Skill
     name="Speed"
     level={92}
@@ -161,7 +163,7 @@ Several gauges in columns, each in its card.
 
 <Columns>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardHeader>Quality</CardHeader>
       <CardBody>
         <Skill name="Tests" level={88} />
@@ -171,7 +173,7 @@ Several gauges in columns, each in its card.
     </Card>
   </Column>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardHeader>Delivery</CardHeader>
       <CardBody>
         <Skill name="Continuous integration" level={100} />
@@ -186,20 +188,50 @@ Several gauges in columns, each in its card.
 
 ## Styling the gauge
 
+<ForTheme framework="tailwind">
+
 The component classes live below the utilities: a `className` set at use wins.
 
 <Skill className="max-w-sm" name="Reduced width" level={55} />
 
-<div className="[&_.dp-skill-fill]:bg-emerald-500">
-  <Skill name="Green fill" level={78} />
-</div>
+The gauge takes its colour from `--dp-skill-color`, which an arbitrary
+property sets:
+
+<Skill className="[--dp-skill-color:#10b981]" name="Green fill" level={78} />
 
 ```mdx
-<div className="[&_.dp-skill-fill]:bg-emerald-500">
-  <Skill name="Green fill" level={78} />
-</div>
+<Skill className="[--dp-skill-color:#10b981]" name="Green fill" level={78} />
 ```
 
+A selector written in a class, such as `[&_.dp-skill-fill]:…`, would not do:
+its `&` reaches the HTML as `&amp;`, and the stylesheet — compiled from the
+rendered pages — never receives the rule.
+
+</ForTheme>
+<ForTheme framework="custom">
+
+The component classes live in the `components` layer, those of the theme
+folder in none: a class of yours set at use wins. The gauge takes its colour
+from `--dp-skill-color`, which a class can set — here `narrow` and `green`,
+from `theme/99-docpensieve.css`:
+
+<Skill className="narrow" name="Reduced width" level={55} />
+
+<Skill className="green" name="Green fill" level={78} />
+
+```mdx
+<Skill className="green" name="Green fill" level={78} />
+```
+
+```css
+.green {
+  --dp-skill-color: #10b981;
+  color: #10b981;
+}
+```
+
+</ForTheme>
+
 ## The fill
 
 It animates as it enters the viewport, through `animation-timeline: view()`,