docpensieve 0.1.0 → 0.1.2

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

@@ -0,0 +1,163 @@
+---
+title: Tree
+description: Collapsible tree, built on native elements.
+---
+
+# Tree
+
+Expanding is done by `<details>`: it works from the keyboard, survives
+printing, and costs not a line of JavaScript.
+
+## A file tree
+
+Click a folder to expand it.
+
+<Tree>
+  <TreeItem label="docpensieve.config.mjs" />
+  <TreeItem label="docs" open>
+    <TreeItem label="v1.0" open>
+      <TreeItem label="index.md" />
+      <TreeItem label="guide">
+        <TreeItem label="installation.md" />
+        <TreeItem label="configuration.md" />
+      </TreeItem>
+      <TreeItem label="components">
+        <TreeItem label="card.mdx" />
+        <TreeItem label="tree.mdx" />
+      </TreeItem>
+    </TreeItem>
+  </TreeItem>
+  <TreeItem label="dist" />
+</Tree>
+
+```mdx
+<Tree>
+  <TreeItem label="docs" open>
+    <TreeItem label="index.md" />
+  </TreeItem>
+</Tree>
+```
+
+## Branch or leaf
+
+The difference is read from the writing, with no prop to set: an entry **with
+children** is a collapsible branch, an entry **without children** is a leaf.
+`open` expands the branch as soon as the page opens.
+
+<Columns>
+  <Column span={6}>
+    <Card className="h-full">
+      <CardHeader>Closed by default</CardHeader>
+      <CardBody>
+        <Tree>
+          <TreeItem label="package">
+            <TreeItem label="index.js" />
+          </TreeItem>
+        </Tree>
+      </CardBody>
+    </Card>
+  </Column>
+  <Column span={6}>
+    <Card className="h-full">
+      <CardHeader>Opened by `open`</CardHeader>
+      <CardBody>
+        <Tree>
+          <TreeItem label="package" open>
+            <TreeItem label="index.js" />
+          </TreeItem>
+        </Tree>
+      </CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+## A plain list
+
+Without any branch, the tree becomes a monospaced list — useful to list
+produced files.
+
+<Tree>
+  <TreeItem label="index.html" />
+  <TreeItem label="versions.json" />
+  <TreeItem label="assets/docpensieve.css" />
+</Tree>
+
+## Something that is not a file
+
+Nothing forces you to describe a file tree. A data structure reads just as
+well.
+
+<Tree>
+  <TreeItem label="config" open>
+    <TreeItem label="projectName : string" />
+    <TreeItem label="siteUrl : string" />
+    <TreeItem label="versions" open>
+      <TreeItem label="slug : string" />
+      <TreeItem label="current : boolean" />
+      <TreeItem label="prerelease : boolean" />
+    </TreeItem>
+    <TreeItem label="theme">
+      <TreeItem label="framework : 'tailwind' | 'custom'" />
+      <TreeItem label="tokens : Record&lt;string, string&gt;" />
+    </TreeItem>
+  </TreeItem>
+</Tree>
+
+## A composite label
+
+`label` accepts content, not just text.
+
+<Tree>
+  <TreeItem
+    label={
+      <span>
+        📦 <strong>package</strong>
+      </span>
+    }
+    open
+  >
+    <TreeItem label={<code>index.js</code>} />
+    <TreeItem
+      label={
+        <span>
+          <em>types</em> — generated
+        </span>
+      }
+    />
+  </TreeItem>
+</Tree>
+
+```mdx
+<TreeItem
+  label={
+    <span>
+      📦 <strong>package</strong>
+    </span>
+  }
+>
+  …
+</TreeItem>
+```
+
+> One caveat: what is written between braces is an **expression**, and the
+> compiler does not read it — its result only exists at render time. A URL
+> placed there is therefore not rewritten and will ignore the deployment
+> prefix. For a link in a label, write the full URL.
+
+## Styling the tree
+
+<Tree className="text-indigo-700 dark:text-indigo-300">
+  <TreeItem label="in colour" open>
+    <TreeItem label="the children inherit" />
+  </TreeItem>
+</Tree>
+
+## What it does not announce
+
+The structure is a nested list, not a `role="tree"`. That role promises a
+screen reader arrow-key navigation that nothing here would implement:
+announcing it would lie about what the page can do.
+
+A `TreeItem` written outside a `Tree` is refused — it would produce an `<li>`
+outside any list, invalid HTML that no browser reports. An entry without a
+label is refused too.

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

@@ -0,0 +1,103 @@
+---
+title: ScrollToTop
+description: Back to the top of the page, set by the shell or by hand.
+---
+
+# ScrollToTop
+
+A link to the `top` fragment, which the HTML specification reserves for the
+top of the document when no element carries that identifier. Nothing to add to
+the template, nothing to load.
+
+## It is already there
+
+**The button is set on every page**, by the shell. Back-to-top is page
+furniture, not content: writing it in every file would mean repeating it
+everywhere, and forgetting it somewhere.
+
+Look at the bottom right of this page while scrolling: it is there without
+anything having asked for it.
+
+To remove it from the whole site:
+
+```js
+// docpensieve.config.mjs
+scrollToTop: false,
+```
+
+## The component, for special cases
+
+`ScrollToTop` stays available when you want a button **in the flow of the
+text**, with its own content — a pointer at the end of a chapter, for
+instance.
+
+<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
+  </ScrollToTop>
+  <ScrollToTop
+    className="!static !inline-flex !w-auto !shadow-none px-4"
+    label="Back to the summit"
+  >
+    ↑ Summit
+  </ScrollToTop>
+  <ScrollToTop
+    className="!static !inline-flex !w-auto !shadow-none px-4 border-indigo-400 text-indigo-700"
+    label="Start reading again"
+  >
+    Start again
+  </ScrollToTop>
+</div>
+
+```mdx
+<ScrollToTop className="!static !inline-flex !w-auto" label="Top of page">
+  Top
+</ScrollToTop>
+```
+
+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.
+
+The accessible name stays set by `label`: without it, the link would announce
+itself by its appearance alone.
+
+## Appearing
+
+It is driven by `animation-timeline: scroll()`: scrolling drives the
+animation, with no event listener. Where the browser does not know that
+property yet, the button simply stays visible — always there is better than
+never there.
+
+Smooth scrolling follows the same caution: it only applies to the pages that
+carry this button, and only if the system does not ask for less motion.
+
+## Room to breathe
+
+Some text, so that the page is long enough to scroll and the appearance of the
+button is noticeable.
+
+The generator produces a static site: each page is a complete HTML file,
+served as is. No hydration step, no bundle to download before reading. That is
+what lets a component like this one be nothing but a link and two style rules.
+
+A version lives on its own branch. The working branch keeps the sources, the
+version branch keeps the output. The two never mix, and going back to an old
+version does not require rebuilding anything.
+
+The shipped components all follow the same rule: they provide the structure,
+and the look is set at use. None of them embeds a hard-coded colour; all of
+them read the tokens of the active theme.
+
+When a page needs interaction, the answer is first sought in native elements —
+`details` for expanding, a link for moving, a CSS transition for appearing.
+Only after that, and rarely, would a script be justified.
+
+This constraint has a happy side effect: a page stays readable in ten years,
+because there is nothing that can stop working. No dependency to update, no
+interface that breaks with the next browser.
+
+And a less happy side effect, better known in advance: what depends on the
+moment is frozen at build time. A page that shows “the offer ends tomorrow”
+will still say so in six months if the site has not been rebuilt. A scheduled
+build is enough to keep it right.

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

@@ -0,0 +1,214 @@
+---
+title: Skill
+description: Level gauge, filled in CSS.
+---
+
+# Skill
+
+A measure within a known range: that is exactly what the `meter` role
+describes, which the gauge carries. The value is therefore announced, whether it
+is shown as a figure or not.
+
+## A gauge
+
+<Skill name="Accessibility" level={85} />
+<Skill name="Performance" level={92} />
+<Skill name="Test coverage" level={64}>
+  Target: 90% on the shipped modules.
+</Skill>
+
+```mdx
+<Skill name="Accessibility" level={85} />
+<Skill name="Test coverage" level={64}>
+  Target: 90%.
+</Skill>
+```
+
+Content passed as a child becomes a comment under the bar.
+
+## As a circle
+
+`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">
+  <Skill name="Accessibility" level={85} shape="circle" />
+  <Skill name="Performance" level={92} shape="circle" />
+  <Skill name="Coverage" level={64} shape="circle" />
+  <Skill name="Types" level={100} shape="circle" />
+</div>
+
+```mdx
+<Skill name="Accessibility" level={85} shape="circle" />
+```
+
+The circle is a decorative SVG: its wrapper carries the role and the value, so
+what is announced does not depend on what is drawn.
+
+Its radius gives it a circumference of exactly a hundred units. The level then
+goes as is into `stroke-dasharray`, with no multiplication or rounding — and
+the entry animation only has to start from zero.
+
+### Size
+
+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' }}>
+  <Skill name="Smaller" level={70} shape="circle" />
+  <Skill name="Also smaller" level={45} shape="circle" />
+</div>
+
+```mdx
+<div style={{ '--dp-skill-size': '4rem' }}>
+  <Skill name="Smaller" level={70} shape="circle" />
+</div>
+```
+
+### With a comment
+
+<Skill name="Translations" level={40} shape="circle">
+  Two languages out of five.
+</Skill>
+
+### Without the figure
+
+<div className="flex flex-wrap">
+  <Skill name="Silent" level={55} shape="circle" showValue={false} />
+</div>
+
+There again, the figure leaves the screen but not what the gauge announces.
+
+## With an icon and a colour
+
+`icon` goes before the name — a [LogoIcon](./logo-icon/) fits there.
+`color` tints the fill **and** the icon: both designate the same thing, and
+seeing them match helps read a column of gauges at a glance.
+
+<Skill name="Speed" level={92} color="#f59e0b" icon={<LogoIcon src="./icons/lightning.svg" />} />
+<Skill name="Safety" level={78} color="#10b981" icon={<LogoIcon src="./icons/shield.svg" />} />
+<Skill name="Documentation" level={64} color="#6366f1" icon={<LogoIcon src="./icons/book.svg" />} />
+
+```mdx
+<Skill name="Speed" level={92} color="#f59e0b" icon={<LogoIcon src="./icons/lightning.svg" />} />
+```
+
+`color` accepts any CSS colour. Without it, the theme's accent colour applies.
+
+### As a circle too
+
+<div className="flex flex-wrap">
+  <Skill
+    name="Speed"
+    level={92}
+    shape="circle"
+    color="#f59e0b"
+    icon={<LogoIcon src="./icons/lightning.svg" />}
+  />
+  <Skill
+    name="Safety"
+    level={78}
+    shape="circle"
+    color="#10b981"
+    icon={<LogoIcon src="./icons/shield.svg" />}
+  />
+  <Skill
+    name="Favourite"
+    level={55}
+    shape="circle"
+    color="#ec4899"
+    icon={<LogoIcon src="./icons/star.svg" />}
+  />
+</div>
+
+### Tinting a whole group
+
+The tint goes through `--dp-skill-color`: setting it on a container applies to
+every gauge it holds.
+
+<div style={{ '--dp-skill-color': '#0ea5e9' }}>
+  <Skill name="First" level={70} />
+  <Skill name="Second" level={45} />
+</div>
+
+```mdx
+<div style={{ '--dp-skill-color': '#0ea5e9' }}>
+  <Skill name="First" level={70} />
+</div>
+```
+
+## The bounds
+
+`level` goes from 0 to 100. Both extremes render with no special case.
+
+<Skill name="Not started" level={0} />
+<Skill name="Done" level={100} />
+
+## Without the figure
+
+<Skill name="Restraint" level={70} showValue={false} />
+
+```mdx
+<Skill name="Restraint" level={70} showValue={false} />
+```
+
+`showValue={false}` removes the percentage **from the screen only**: the gauge
+keeps announcing it to screen readers. Hiding a piece of information is not
+deleting it.
+
+## A dashboard
+
+Several gauges in columns, each in its card.
+
+<Columns>
+  <Column span={6}>
+    <Card className="h-full">
+      <CardHeader>Quality</CardHeader>
+      <CardBody>
+        <Skill name="Tests" level={88} />
+        <Skill name="Types" level={95} />
+        <Skill name="Documentation" level={72} />
+      </CardBody>
+    </Card>
+  </Column>
+  <Column span={6}>
+    <Card className="h-full">
+      <CardHeader>Delivery</CardHeader>
+      <CardBody>
+        <Skill name="Continuous integration" level={100} />
+        <Skill name="Translations" level={40}>
+          Two languages out of five.
+        </Skill>
+        <Skill name="Site online" level={100} />
+      </CardBody>
+    </Card>
+  </Column>
+</Columns>
+
+## Styling the gauge
+
+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>
+
+```mdx
+<div className="[&_.dp-skill-fill]:bg-emerald-500">
+  <Skill name="Green fill" level={78} />
+</div>
+```
+
+## The fill
+
+It animates as it enters the viewport, through `animation-timeline: view()`,
+over a range wide enough for the movement to be seen rather than flicker.
+Where that property is missing, or if the system asks for less motion, the bar
+is full from the start — the value stays readable, which is what matters.
+
+## What it refuses
+
+A level outside 0–100 stops the build, as does a gauge without a name, a level
+that is not a number, or an unknown `shape`. A silent or overflowing bar goes
+unnoticed on review.

package/starter/02-components/08-logo-icon.mdx

@@ -0,0 +1,122 @@
+---
+title: LogoIcon
+description: SVG icon inlined in the page at build time.
+---
+
+# LogoIcon
+
+The file is read at build time and its content placed in the page. That is
+what lets it take its colour from `currentColor` and be sized like the rest of
+the text — impossible through an `img` tag, which isolates the document.
+
+## An icon
+
+<LogoIcon src="./icons/book.svg" label="Documentation" />
+<LogoIcon src="./icons/star.svg" label="Favourite" />
+<LogoIcon src="./icons/lightning.svg" label="Fast" />
+<LogoIcon src="./icons/shield.svg" label="Verified" />
+
+```mdx
+<LogoIcon src="./icons/book.svg" label="Documentation" />
+```
+
+A relative path starts from the page, an absolute path from the version
+folder. Nothing can leave it: a page does not read the rest of the machine.
+
+## It follows the text
+
+Placed in a text, the icon takes its size and colour.
+
+<div className="text-indigo-600 text-2xl">
+  <LogoIcon src="./icons/star.svg" /> at the size and colour of the text
+</div>
+
+<div className="text-sm text-slate-500">
+  <LogoIcon src="./icons/star.svg" /> and here, smaller and greyer
+</div>
+
+## Sizes
+
+`size` accepts any CSS length.
+
+<div className="flex items-end gap-4 text-emerald-600">
+  <LogoIcon src="./icons/shield.svg" size="1rem" />
+  <LogoIcon src="./icons/shield.svg" size="2rem" />
+  <LogoIcon src="./icons/shield.svg" size="3rem" />
+  <LogoIcon src="./icons/shield.svg" size="4rem" />
+</div>
+
+```mdx
+<LogoIcon src="./icons/shield.svg" size="3rem" className="text-emerald-600" />
+```
+
+The colour only follows if the file relies on `currentColor` rather than on a
+fixed colour.
+
+## In a list
+
+<ul className="list-none pl-0 space-y-2">
+  <li className="flex items-center gap-2">
+    <LogoIcon src="./icons/lightning.svg" size="1.1rem" className="text-amber-500" /> No script to
+    load
+  </li>
+  <li className="flex items-center gap-2">
+    <LogoIcon src="./icons/shield.svg" size="1.1rem" className="text-emerald-600" /> Links are read
+    back before publishing
+  </li>
+  <li className="flex items-center gap-2">
+    <LogoIcon src="./icons/book.svg" size="1.1rem" className="text-indigo-600" /> One version per
+    branch
+  </li>
+</ul>
+
+## At the head of a card
+
+<Columns>
+  <Column span={6}>
+    <Card className="h-full">
+      <CardBody>
+        <LogoIcon src="./icons/lightning.svg" size="1.6rem" className="text-amber-500" />
+        <strong className="block mt-2 mb-1 text-base font-semibold">Fast</strong>
+
+        No hydration, no bundle to download before reading.
+      </CardBody>
+    </Card>
+
+  </Column>
+  <Column span={6}>
+    <Card className="h-full">
+      <CardBody>
+        <LogoIcon src="./icons/shield.svg" size="1.6rem" className="text-emerald-600" />
+        <strong className="block mt-2 mb-1 text-base font-semibold">Verified</strong>
+
+        Dead links and invalid markup stop the publication.
+      </CardBody>
+    </Card>
+
+  </Column>
+</Columns>
+
+## Decorative or meaningful
+
+Without `label`, the icon is treated as decorative and hidden from screen
+readers — which is right when nearby text already says the same thing. With
+`label`, it becomes a described image.
+
+```mdx
+<LogoIcon src="./icons/star.svg" />
+<LogoIcon src="./icons/star.svg" label="Favourite" />
+```
+
+In the list above, the icons have no `label`: the text next to them already
+carries the meaning, and announcing it twice would tell nothing.
+
+## What it refuses
+
+A missing file, a file without an `svg` tag, a target leaving the version
+folder: each one stops the build, naming the expected path. A missing icon
+would otherwise leave an empty box that nobody notices.
+
+The scripts and event handlers present in a file are removed before inlining.
+The produced site loads no JavaScript, and a component is not going to
+introduce any.

package/starter/02-components/icons/banner.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 120" role="img" aria-label="Decorative banner">
+  <defs>
+    <linearGradient id="dp-b" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#6366f1" />
+      <stop offset="1" stop-color="#0ea5e9" />
+    </linearGradient>
+  </defs>
+  <rect width="320" height="120" fill="url(#dp-b)" />
+  <g fill="none" stroke="#ffffff" stroke-opacity="0.45" stroke-width="2">
+    <circle cx="62" cy="60" r="26" />
+    <circle cx="160" cy="60" r="40" />
+    <circle cx="258" cy="60" r="26" />
+    <path d="M0 92h320M0 28h320" />
+  </g>
+</svg>

package/starter/02-components/icons/book.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20" />
+  <path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z" />
+</svg>

package/starter/02-components/icons/lightning.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
+  <path d="M13 2 4 14h6l-1 8 9-12h-6z" />
+</svg>

package/starter/02-components/icons/shield.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" />
+  <path d="m9 12 2 2 4-4" />
+</svg>

package/starter/02-components/icons/star.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
+  <path d="m12 2 2.9 6.26 6.85.7-5.1 4.6 1.44 6.72L12 16.9l-6.09 3.38 1.44-6.72-5.1-4.6 6.85-.7z" />
+</svg>

package/starter/02-components/index.md

@@ -0,0 +1,41 @@
+---
+title: Components
+description: The components available in every page, without an import.
+---
+
+# Components
+
+These components can be used in any `.mdx` page **without an import**.
+
+They provide the **structure** — wrappers, separators, spacing. The look is set
+with `className`, in utilities of the active theme:
+
+```mdx
+<Card className="max-w-sm">
+  <CardHeader className="text-center font-bold">Title</CardHeader>
+</Card>
+```
+
+The component classes live in the `components` layer, below the utilities: a
+`className` set at use always wins.
+
+## Available
+
+- [Card](./card/) — card, with header, body, footer and image
+- [Columns](./columns/) — column grid
+- [TimeTimer](./time-timer/) — display depending on a date
+- [Tooltip](./tooltip/) — tooltip on hover and from the keyboard
+- [Tree](./tree/) — collapsible tree
+- [ScrollToTop](./scroll-to-top/) — back to the top of the page
+- [Skill](./skill/) — level gauge
+- [LogoIcon](./logo-icon/) — SVG icon inlined in the page
+
+## Without JavaScript
+
+The produced site loads no script. Whatever needs interaction therefore goes
+through native elements or through CSS: `details` for expanding, a link for
+moving, `animation-timeline` for appearing on scroll.
+
+When the browser does not know one of these properties yet, the component stays
+usable in its simplest state — visible, full, expanded. None of them waits for
+a capability to work.