docpensieve 0.1.0 → 0.1.2

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

@@ -0,0 +1,195 @@
+---
+title: Card
+description: Structured card, with header, body, footer and image.
+---
+
+# Card
+
+## The simplest
+
+<Card className="max-w-sm">
+  <CardBody>A card reduced to its body.</CardBody>
+</Card>
+
+```mdx
+<Card className="max-w-sm">
+  <CardBody>A card reduced to its body.</CardBody>
+</Card>
+```
+
+## With its three parts
+
+<Card className="max-w-sm">
+  <CardHeader>Header</CardHeader>
+  <CardBody>
+    The body of the card. It takes the remaining space when several cards sit side by side.
+  </CardBody>
+  <CardFooter>Card footer</CardFooter>
+</Card>
+
+## With an image
+
+`CardImage` goes wherever you want in the card. At the top or at the bottom, it
+follows the corners; between two blocks, it stays square.
+
+<Columns>
+  <Column span={6}>
+    <Card>
+      <CardImage src="./icons/banner.svg" alt="" />
+      <CardHeader>Image at the top</CardHeader>
+      <CardBody>The top corners follow those of the card.</CardBody>
+    </Card>
+  </Column>
+  <Column span={6}>
+    <Card>
+      <CardHeader>Image at the bottom</CardHeader>
+      <CardBody>The bottom corners follow those of the card.</CardBody>
+      <CardImage src="./icons/banner.svg" alt="" />
+    </Card>
+  </Column>
+</Columns>
+
+```mdx
+<Card>
+  <CardImage src="./icons/banner.svg" alt="" />
+  <CardBody>…</CardBody>
+</Card>
+```
+
+`alt` defaults to the empty string: a decorative image is thus passed over by
+screen readers, rather than announced by its file name. An image that carries
+meaning deserves a written `alt`.
+
+## A grid of cards
+
+It is the most common use. `h-full` aligns the heights whatever the content.
+
+<Columns>
+  <Column>
+    <Card className="h-full">
+      <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="h-full">
+      <CardHeader>Dependency-free</CardHeader>
+      <CardBody>The delivered HTML loads nothing.</CardBody>
+    </Card>
+  </Column>
+  <Column>
+    <Card className="h-full">
+      <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="h-full">…</Card>
+  </Column>
+</Columns>
+```
+
+## Elevation
+
+<Card className="max-w-sm" elevated>
+  <CardBody>This card carries a shadow.</CardBody>
+</Card>
+
+```mdx
+<Card elevated>…</Card>
+```
+
+## Fully clickable
+
+<Card className="max-w-sm" href="./columns/">
+  <CardHeader>Go to the columns</CardHeader>
+  <CardBody>The whole card is a link, not just the title.</CardBody>
+</Card>
+
+```mdx
+<Card href="./columns/">…</Card>
+```
+
+A relative target starts from the page, an absolute target from the version
+root — the same rules as for a Markdown link.
+
+## A highlighted figure
+
+Nothing specific to the component: a card, a little typography, and the footer
+carrying the caption.
+
+<Columns>
+  <Column span={4}>
+    <Card className="h-full text-center">
+      <CardBody>
+        <div className="text-4xl font-semibold text-indigo-600">0</div>
+        <div className="text-sm">bytes of JavaScript</div>
+      </CardBody>
+      <CardFooter>on every delivered page</CardFooter>
+    </Card>
+  </Column>
+  <Column span={4}>
+    <Card className="h-full text-center">
+      <CardBody>
+        <div className="text-4xl font-semibold text-indigo-600">8</div>
+        <div className="text-sm">components</div>
+      </CardBody>
+      <CardFooter>usable without an import</CardFooter>
+    </Card>
+  </Column>
+  <Column span={4}>
+    <Card className="h-full text-center">
+      <CardBody>
+        <div className="text-4xl font-semibold text-indigo-600">1</div>
+        <div className="text-sm">stylesheet</div>
+      </CardBody>
+      <CardFooter>per version</CardFooter>
+    </Card>
+  </Column>
+</Columns>
+
+## A warning card
+
+<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">
+    A generated site can compile without error and contain dead links.
+    <code>docpensieve check</code> reads the output back.
+  </CardBody>
+</Card>
+
+## The look through className
+
+The component offers no typography prop: the theme's utilities take care of
+it, and win over the default style.
+
+<Card className="max-w-sm border-indigo-400 bg-indigo-50">
+  <CardHeader className="text-center uppercase tracking-wide text-indigo-700">
+    Centred, in capitals
+  </CardHeader>
+  <CardBody className="text-sm italic">Small, italic body.</CardBody>
+</Card>
+
+```mdx
+<Card className="border-indigo-400 bg-indigo-50">
+  <CardHeader className="text-center uppercase tracking-wide text-indigo-700">
+    Centred, in capitals
+  </CardHeader>
+  <CardBody className="text-sm italic">Small, italic body.</CardBody>
+</Card>
+```
+
+The component rules live in the `components` layer, below the utilities: a
+`className` set at use always wins, even to undo the default style.
+
+<Card className="max-w-sm border-0 shadow-none bg-transparent">
+  <CardBody className="px-0">No border, no background, no inner padding.</CardBody>
+</Card>

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

@@ -0,0 +1,193 @@
+---
+title: Columns
+description: Column grid, equal or in twelfths.
+---
+
+# Columns
+
+A **grid**: each block is placed, with its width. Not to be confused with CSS
+multi-column, where content flows from one column to the next — see below, it
+needs no component.
+
+## Equal columns
+
+Without an imposed width, the columns share the space equally, whatever their
+content.
+
+<Columns>
+  <Column>
+    <Card>
+      <CardBody>First</CardBody>
+    </Card>
+  </Column>
+  <Column>
+    <Card>
+      <CardBody>
+        Second, with a noticeably longer text to check that the columns keep the same width.
+      </CardBody>
+    </Card>
+  </Column>
+  <Column>
+    <Card>
+      <CardBody>Third</CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+```mdx
+<Columns>
+  <Column>…</Column>
+  <Column>…</Column>
+</Columns>
+```
+
+## Widths in twelfths
+
+`span` is the number of **tracks** a column takes out of twelve: `span={6}` for
+a half, `span={8}` for two thirds, `span={3}` for a quarter. Twelve because
+twelve divides by two, three, four and six — halves, thirds, quarters and
+sixths all fall right.
+
+A value outside 1–12 stops the build, as does a row that mixes columns with and
+without a width: the column without a width would take only one track out of
+twelve, a sliver where the author expected a column.
+
+<Columns>
+  <Column span={8}>
+    <Card>
+      <CardBody>span={8}</CardBody>
+    </Card>
+  </Column>
+  <Column span={4}>
+    <Card>
+      <CardBody>span={4}</CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+```mdx
+<Columns>
+  <Column span={8}>…</Column>
+  <Column span={4}>…</Column>
+</Columns>
+```
+
+A `Column` written outside a `Columns` is refused: on its own, it would
+produce nothing visible, and the error would take a long time to find.
+
+## Spacing the columns
+
+`span` sets the **width** of a column, `gap` the **space between** columns: two
+independent settings. The grid subtracts the gaps by itself, so spacing the
+columns distorts no width.
+
+<Columns className="gap-10">
+  <Column>
+    <Card>
+      <CardBody>The gap widens</CardBody>
+    </Card>
+  </Column>
+  <Column>
+    <Card>
+      <CardBody>without touching the widths</CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+```mdx
+<Columns className="gap-10">…</Columns>
+```
+
+## An aside next to the text
+
+The most useful layout in documentation: the main point wide, the remark
+narrow.
+
+<Columns>
+  <Column span={8}>
+
+The compiler plugins rewrite the URLs of the tree built from the Markdown. That
+work happens **before** the components are rendered: a target written in a prop
+escapes them, and must resolve itself.
+
+That is why every rendered page is announced to the components, just as the
+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">
+        A component that produces a URL resolves it itself, following the same rules as a
+        Markdown link.
+      </CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+```mdx
+<Columns>
+  <Column span={8}>The point</Column>
+  <Column span={4}>The remark</Column>
+</Columns>
+```
+
+## Two code columns
+
+Compare two spellings side by side.
+
+<Columns>
+  <Column span={6}>
+
+```js
+versions: [{ slug: 'v1.0', current: true }];
+```
+
+  </Column>
+  <Column span={6}>
+
+```js
+versions: [
+  { slug: 'v1.1', prerelease: true },
+  { slug: 'v1.0', current: true },
+];
+```
+
+  </Column>
+</Columns>
+
+## 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.
+
+<div className="columns-2 gap-6 sm:columns-3">
+  <Card className="mb-6 break-inside-avoid">
+    <CardBody>One</CardBody>
+  </Card>
+  <Card className="mb-6 break-inside-avoid">
+    <CardBody>Two, a little longer, so that the heights differ.</CardBody>
+  </Card>
+  <Card className="mb-6 break-inside-avoid">
+    <CardBody>Three</CardBody>
+  </Card>
+  <Card className="mb-6 break-inside-avoid">
+    <CardBody>Four</CardBody>
+  </Card>
+  <Card className="mb-6 break-inside-avoid">
+    <CardBody>Five</CardBody>
+  </Card>
+</div>
+
+```mdx
+<div className="columns-2 gap-6 sm:columns-3">…</div>
+```
+
+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.
+
+## On small screens
+
+Below tablet width, the grid columns stack one under the other. Shrink the
+window to check.

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

@@ -0,0 +1,120 @@
+---
+title: TimeTimer
+description: Show content during a period, with fallbacks before and after.
+---
+
+# TimeTimer
+
+`TimeTimer` chooses what to show depending on the date. On a static site,
+“right now” means the moment of the **build**, not of reading — a scheduled
+build is enough to keep it right.
+
+## A past date
+
+<TimeTimer date="01/01/2020">
+  During the day of 1 January 2020.
+  <FallbackBefore>Before that date.</FallbackBefore>
+  <FallbackAfter>That date has passed — the “after” fallback is what shows.</FallbackAfter>
+</TimeTimer>
+
+```mdx
+<TimeTimer date="01/01/2020">
+  During the day of 1 January 2020.
+  <FallbackBefore>Before that date.</FallbackBefore>
+  <FallbackAfter>That date has passed.</FallbackAfter>
+</TimeTimer>
+```
+
+A date alone covers the **whole day**.
+
+## A future date
+
+<TimeTimer date="01/01/2090">
+  During the day of 1 January 2090.
+  <FallbackBefore>That date is still to come — the “before” fallback is what shows.</FallbackBefore>
+  <FallbackAfter>After that date.</FallbackAfter>
+</TimeTimer>
+
+## An ongoing period
+
+<TimeTimer start="01/01/2020" duration="36500d">
+  This period is ongoing: the main content is what shows.
+  <FallbackBefore>Not started yet.</FallbackBefore>
+  <FallbackAfter>Already over.</FallbackAfter>
+</TimeTimer>
+
+```mdx
+<TimeTimer start="01/01/2020" duration="36500d">
+  …
+</TimeTimer>
+```
+
+`duration` is written `30d` (days), `2h` (hours) or `45m` (minutes). A
+misspelt duration **stops the build**: a typo that silently makes a block
+disappear is exactly what must be avoided.
+
+## With a time
+
+The full format is `DD/MM/YYYY HH:mm`. Without a year, the current year is
+used.
+
+<TimeTimer start="01/01/2020 08:30" duration="36500d">
+  A period that started at 8:30.
+</TimeTimer>
+
+```mdx
+<TimeTimer start="01/01/2020 08:30" duration="2h">
+  …
+</TimeTimer>
+```
+
+## Without a fallback
+
+Outside the period and without a fallback, the component shows **nothing**.
+The next line is empty, and that is on purpose:
+
+<TimeTimer date="01/01/2020">This content does not show.</TimeTimer>
+
+## Bounding a fallback
+
+`FallbackBefore` accepts `start`, `FallbackAfter` accepts `end`: the fallback
+then only shows within that window, and nothing outside it. That is what lets
+you announce an event a few days ahead, without the announcement lingering for
+months.
+
+```mdx
+<TimeTimer date="24/12/2090">
+  It is today.
+  <FallbackBefore start="17/12/2090">In less than a week.</FallbackBefore>
+</TimeTimer>
+```
+
+## A real use
+
+An announcement banner that removes itself:
+
+<Card className="border-indigo-400 bg-indigo-50 dark:bg-indigo-950/30">
+  <CardBody>
+    <TimeTimer start="01/01/2020" duration="36500d">
+      **Version 1.1 in preparation.** New features are written in this version.
+      <FallbackAfter>Version 1.1 is out.</FallbackAfter>
+    </TimeTimer>
+  </CardBody>
+</Card>
+
+## Local time or UTC
+
+By default, dates are read in the time zone of the machine that builds.
+`strict` reads them in UTC — useful when the build runs in continuous
+integration, whose time zone is not yours.
+
+```mdx
+<TimeTimer date="24/12/2090" strict>
+  …
+</TimeTimer>
+```
+
+## What it refuses
+
+A misspelt duration stops the build, and so does an invalid date. The message
+names the faulty value and recalls the expected format.

package/starter/02-components/04-tooltip.mdx

@@ -0,0 +1,100 @@
+---
+title: Tooltip
+description: Tooltip on hover and from the keyboard, without JavaScript.
+---
+
+# Tooltip
+
+The bubble is a real element that CSS reveals. It therefore appears on hover
+**and on keyboard focus**, and it is linked to the term through
+`aria-describedby`: a screen reader announces it instead of ignoring it.
+
+## On hover, from the keyboard
+
+Hover the term with the mouse, or reach it with the Tab key.
+
+The <Tooltip text="Turning the sources into HTML pages ready to serve.">build</Tooltip> produces a complete folder, and the <Tooltip text="All the pages of one version of the documentation.">version</Tooltip> is its root.
+
+```mdx
+The <Tooltip text="Turning the sources…">build</Tooltip> produces a folder.
+```
+
+## The four sides
+
+Hover each one: <Tooltip text="Above" placement="top">top</Tooltip>, <Tooltip text="Below" placement="bottom">bottom</Tooltip>, <Tooltip text="On the left" placement="left">left</Tooltip> and <Tooltip text="On the right" placement="right">right</Tooltip>.
+
+```mdx
+<Tooltip text="On the right" placement="right">
+  term
+</Tooltip>
+```
+
+The side is chosen according to the available space: `top` by default,
+`bottom` when the term is at the top of the page, `left` or `right` in a narrow
+column.
+
+## On a technical term
+
+Useful to explain an identifier without weighing down the sentence.
+
+The <Tooltip text="Deployment prefix, derived from the sub-path of siteUrl when it is not written."><code>baseUrl</code></Tooltip> field prefixes every internal link, and <Tooltip text="Version served by default. At most one."><code>current</code></Tooltip> designates the one the root serves.
+
+```mdx
+The <Tooltip text="Deployment prefix."><code>baseUrl</code></Tooltip> field prefixes the links.
+```
+
+## In a table
+
+| Field        | Role                                                                                                 |
+| ------------ | ---------------------------------------------------------------------------------------------------- |
+| `slug`       | <Tooltip text="It shows up in /versions/<slug>/ and gives the branch its name.">Identifier</Tooltip> |
+| `current`    | <Tooltip text="The site root redirects to it.">Version served by default</Tooltip>                   |
+| `prerelease` | <Tooltip text="Banner on every page, and noindex in the head.">Version in preparation</Tooltip>      |
+
+## In a card
+
+A card does not clip what sticks out: the bubble comes out of it.
+
+<Columns>
+  <Column span={6}>
+    <Card>
+      <CardBody>
+        A <Tooltip text="The bubble comes out of the card, it is not cut.">term</Tooltip> in a card.
+      </CardBody>
+    </Card>
+  </Column>
+  <Column span={6}>
+    <Card>
+      <CardBody>
+        And{' '}
+        <Tooltip text="Opened downwards." placement="bottom">
+          another
+        </Tooltip>{' '}
+        below.
+      </CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+## A long text
+
+The bubble is capped at about sixteen rem wide, then wraps.
+
+See the <Tooltip text="A published version stays in the state in which it was produced. Rebuilding it is never necessary, and nothing would guarantee it gives the same result years later.">reason for version branches</Tooltip> for the details.
+
+## What it cannot do
+
+The bubble is positioned absolutely: inside a container that **clips its
+overflow** — an `overflow: hidden` — it will be cut. That is the limit of a
+tooltip without JavaScript, and it is accepted: placing the bubble outside the
+flow would take a script on every page.
+
+The shipped components avoid that clipping wherever they can — a `Card` rounds
+the corners of its image one by one rather than clipping its content.
+
+The bubble does not close with the Escape key: listening for it would take a
+script, and the site loads none. It disappears when the pointer or the focus
+leaves the term.
+
+A `Tooltip` without text stops the build: a hover with no effect goes
+unnoticed for a long time. So does an unknown side.