@docpensieve/components 0.1.0

package/types/card.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Card and its parts.
+ *
+ * The component provides the **structure** — the wrapper, the separators, the
+ * spacing. The look is set through `className`, with the utilities of the
+ * active theme. One prop per typographic setting would mean reimplementing,
+ * less well, what CSS already does.
+ *
+ * Classes come from the theme (ADR-007), never from a hard-coded framework.
+ *
+ * The files of this package are plain JavaScript, with no build step: no JSX,
+ * hence `createElement` — shortened to `h` for readability.
+ *
+ * @module @docpensieve/components/card
+ */
+export type PartProps = {
+    /**
+     * Classes added to the component's own.
+     */
+    className?: string;
+    style?: object;
+    children?: any;
+};
+/**
+ * Card container.
+ *
+ * @param {PartProps & { elevated?: boolean, href?: string }} props
+ *   `elevated` adds a shadow. `href` makes the whole card clickable, rather
+ *   than a link on the title alone that would leave the rest inert.
+ */
+export declare function Card({ className, style, children, elevated, href }: PartProps & {
+    elevated?: boolean;
+    href?: string;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+    href?: string | undefined;
+}, HTMLElement>;
+export declare const CardHeader: (props: PartProps) => any;
+export declare const CardBody: (props: PartProps) => any;
+export declare const CardFooter: (props: PartProps) => any;
+/**
+ * Image at the top of a card.
+ *
+ * `src` resolves as in Markdown — relative to the page, absolute from the
+ * version root. The compiler plugins cannot handle it: they work on the
+ * Markdown tree, before React renders anything. So the component does it
+ * itself (ADR-006).
+ *
+ * @param {{
+ *   className?: string, style?: object, src?: string,
+ *   alt?: string, title?: string, srcSet?: string, sizes?: string,
+ * }} props `alt` defaults to the empty string: without that attribute, a
+ *   screen reader would announce the file URL.
+ */
+export declare function CardImage({ className, style, src, alt, ...rest }: {
+    className?: string;
+    style?: object;
+    src?: string;
+    alt?: string;
+    title?: string;
+    srcSet?: string;
+    sizes?: string;
+}): import("react").DetailedReactHTMLElement<{
+    title?: string;
+    srcSet?: string;
+    sizes?: string;
+    className: string | undefined;
+    style: object | undefined;
+    src: string | undefined;
+    alt: string;
+}, HTMLElement>;

package/types/classes.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Resolution of component classes.
+ *
+ * A component never writes a framework class. It asks for the class of its
+ * slot, and the theme answers — or not. Without an answer, the fallback is a
+ * `dp-*` class that the package stylesheet styles on the `--dp-*` tokens: the
+ * component therefore follows the active palette without knowing anything
+ * about it (ADR-007).
+ *
+ * @module @docpensieve/components/classes
+ */
+/**
+ * Declares the theme table for the whole compilation.
+ *
+ * @param {Record<string, string>} [classes]
+ */
+export declare function setThemeClasses(classes?: Record<string, string>): void;
+/** @returns {Record<string, string>} The current table, for inspection. */
+export declare function getThemeClasses(): Record<string, string>;
+/**
+ * Converts a slot name into a fallback class.
+ *
+ * @example
+ * fallbackClass('cardHeader')  // 'dp-card-header'
+ *
+ * @param {string} slot
+ * @returns {string}
+ */
+export declare function fallbackClass(slot: string): string;
+/**
+ * Class of a slot, variants included.
+ *
+ * @example
+ * cls('card')                  // 'dp-card'
+ * cls('card', 'shadow')        // 'dp-card dp-card--shadow'
+ * cls('alert', false && 'x')   // 'dp-alert' — falsy values are ignored
+ *
+ * @param {string} slot Slot name.
+ * @param {...unknown} modifiers Variants, each one suffixed as `--variant`.
+ *   Falsy values are ignored, which allows writing `cls('card', shadow && shadow)`.
+ * @returns {string}
+ */
+export declare function cls(slot: string, ...modifiers: unknown[]): string;
+/**
+ * Joins classes while ignoring falsy values.
+ *
+ * A minimal equivalent of `clsx`: one more dependency is not worth it for six
+ * lines.
+ *
+ * @param {...unknown} parts
+ * @returns {string | undefined} `undefined` when nothing is left, to avoid a
+ *   `class=""` in the produced HTML.
+ */
+export declare function classNames(...parts: unknown[]): string | undefined;

package/types/columns.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Column grid.
+ *
+ * Not to be confused with CSS multi-column (`column-count`), where content
+ * *flows* from one column to the next as in a newspaper. Here every block is
+ * placed explicitly: it is a grid, not a flow. For a flow, the theme's
+ * utilities are enough, without a component.
+ *
+ * Two layouts, depending on what the row holds:
+ *
+ * - **no declared width** — the columns share the space equally, whatever
+ *   their number;
+ * - **declared widths** — twelve tracks, and each column takes the number it
+ *   asks for.
+ *
+ * The grid works out the gap between columns by itself: a width therefore has
+ * no calculation to make, and changing the gap breaks nothing.
+ *
+ * Classes come from the theme (ADR-007), never from a hard-coded framework.
+ *
+ * @module @docpensieve/components/columns
+ */
+/**
+ * Row of columns.
+ *
+ * The gap is set through `className` or `style`, with the theme's utilities:
+ * the grid recomputes the widths by itself.
+ *
+ * @param {{ className?: string, style?: object, children?: any }} props
+ */
+export declare function Columns({ className, style, children }: {
+    className?: string;
+    style?: object;
+    children?: any;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<{
+    sized: boolean;
+} | null>>;
+/**
+ * Column of a row.
+ *
+ * @param {{ className?: string, style?: object, children?: any, span?: number }} props
+ *   `span` is the number of tracks taken out of twelve — `span={6}` for a
+ *   half, `span={8}` for two thirds. Twelve because twelve divides by two,
+ *   three, four and six. Without `span`, the columns share the space equally.
+ * @throws {DocPensieveError} Outside a `Columns`, or when the row mixes
+ *   columns with and without a width.
+ */
+export declare function Column({ className, style, children, span }: {
+    className?: string;
+    style?: object;
+    children?: any;
+    span?: number;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+}, HTMLElement>;

package/types/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @docpensieve/components — global components available in MDX.
+ *
+ * React is a build-only dependency: the generated HTML loads no React
+ * runtime. The components are therefore **static** — no state, no event
+ * listener. Whatever needs interaction goes through CSS or through native
+ * HTML elements such as `<details>`.
+ *
+ * @module @docpensieve/components
+ */
+export { classNames, cls, fallbackClass, getThemeClasses, setThemeClasses } from './classes.js';
+export { Card, CardBody, CardFooter, CardHeader, CardImage } from './card.js';
+export { Column, Columns } from './columns.js';
+export { FallbackAfter, FallbackBefore, TimeTimer } from './time-timer.js';
+export { TOOLTIP_PLACEMENTS, Tooltip } from './tooltip.js';
+export { Tree, TreeItem } from './tree.js';
+export { ScrollToTop } from './scroll-to-top.js';
+export { SKILL_SHAPES, Skill } from './skill.js';
+export { LogoIcon } from './logo-icon.js';
+export { componentsCss } from './styles.js';
+export { getSiteContext, resolveFile, resolveUrl, setSiteContext } from './site.js';
+export { builtinComponents, createRegistry, listComponentNames } from './registry.js';

package/types/logo-icon.d.ts

@@ -0,0 +1,39 @@
+/**
+ * SVG icon inlined at build time.
+ *
+ * The file is read once and its content placed in the page. That is what
+ * lets it take its colour from `currentColor` and be styled like everything
+ * else — impossible through an `img` tag, which isolates the document.
+ *
+ * @module @docpensieve/components/logo-icon
+ */
+/**
+ * Project SVG icon, inlined in the page.
+ *
+ * @example
+ * <LogoIcon src="./icons/book.svg" label="Documentation" />
+ *
+ * @param {{
+ *   className?: string, style?: object,
+ *   src?: string, label?: string, size?: string,
+ * }} props `label` describes the icon; without it the icon is treated as
+ *   decorative and hidden from screen readers — which is right when nearby
+ *   text already says the same thing. `size` accepts any CSS length.
+ * @throws {DocPensieveError} Without `src`, or when the file cannot be read.
+ */
+export declare function LogoIcon({ className, style, src, label, size }: {
+    className?: string;
+    style?: object;
+    src?: string;
+    label?: string;
+    size?: string;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+    role: "img" | undefined;
+    'aria-label': string | undefined;
+    'aria-hidden': "true" | undefined;
+    dangerouslySetInnerHTML: {
+        __html: string;
+    };
+}, HTMLElement>;

package/types/registry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Registry of global components.
+ *
+ * The components registered here are passed to @mdx-js/mdx as the
+ * `components` table: they become usable in any `.mdx` without an import.
+ *
+ * @module @docpensieve/components/registry
+ */
+/**
+ * Components shipped with DocPensieve.
+ * @type {Record<string, Function>}
+ */
+export declare const builtinComponents: Record<string, Function>;
+/**
+ * Builds the component table passed to the MDX compiler.
+ *
+ * @param {Record<string, Function>} [userComponents] Project components, which
+ *   override the built-in components of the same name.
+ * @returns {Record<string, Function>} Table ready for @mdx-js/mdx.
+ */
+export declare function createRegistry(userComponents?: Record<string, Function>): Record<string, Function>;
+/**
+ * Lists the available component names — useful for a readable error message
+ * when an `.mdx` references an unknown component.
+ *
+ * @param {Record<string, Function>} registry
+ * @returns {string[]} Names sorted alphabetically.
+ */
+export declare function listComponentNames(registry: Record<string, Function>): string[];

package/types/scroll-to-top.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Back to the top of the page.
+ *
+ * No JavaScript: a link to the `top` fragment, which the HTML specification
+ * reserves for the top of the document when no element carries that
+ * identifier. The button therefore works without adding anything to the page.
+ *
+ * It only shows once the page has scrolled, through `animation-timeline`.
+ * Where the browser ignores it, it simply stays visible: a button always there
+ * is better than a button never there.
+ *
+ * @module @docpensieve/components/scroll-to-top
+ */
+/**
+ * Back-to-top button.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any, label?: string,
+ * }} props `label` is read by screen readers. The children replace the arrow
+ *   with whatever you want.
+ */
+export declare function ScrollToTop({ className, style, children, label }: {
+    className?: string;
+    style?: object;
+    children?: any;
+    label?: string;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+    href: string;
+    'aria-label': string;
+}, HTMLElement>;

package/types/site.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Page context handed to components.
+ *
+ * The compiler plugins rewrite the URLs of the tree built from the Markdown,
+ * but that work happens **before** React renders the components: a link
+ * produced by a component escapes them. This module gives it what it needs
+ * to resolve itself, following the same rules (ADR-006).
+ *
+ * It also carries what is needed to find a **file** of the version, which a
+ * component that includes a resource at build time requires.
+ *
+ * @module @docpensieve/components/site
+ */
+export type SiteContext = {
+    /**
+     * URL of the page being rendered.
+     */
+    url: string;
+    /**
+     * Folder of the source file, mapped into URL
+     * space. Base of relative targets: the page URL has one more level.
+     */
+    dirUrl?: string;
+    /**
+     * Version root, deployment prefix included.
+     */
+    basePath: string;
+    /**
+     * Source file of the page, on disk.
+     */
+    filepath?: string;
+    /**
+     * Source folder of the version.
+     */
+    sourceDir?: string;
+};
+/**
+ * Declares the page being rendered.
+ *
+ * Set by the generator before every page, like the class table.
+ *
+ * @param {Partial<SiteContext>} [page]
+ */
+export declare function setSiteContext(page?: Partial<SiteContext>): void;
+/** @returns {SiteContext} The current context. */
+export declare function getSiteContext(): SiteContext;
+/**
+ * Resolves a target written by an author into a site URL.
+ *
+ * Same rules as for Markdown content: a relative target resolves against the
+ * page's folder, an absolute target starts from the version root.
+ *
+ * @param {string | undefined} target
+ * @returns {string | undefined} The resolved target, or as is when external.
+ */
+export declare function resolveUrl(target: string | undefined): string | undefined;
+/**
+ * Resolves a target into a file path, for a resource read at build time.
+ *
+ * Same landmarks as for a URL, mapped to the disk: a relative target starts
+ * from the page's file, an absolute one from the version folder. Nothing can
+ * leave that folder — a page does not read the rest of the machine.
+ *
+ * @param {string} target
+ * @returns {string} Absolute path, inside the source folder.
+ * @throws {Error} When the context is missing or the target escapes it.
+ */
+export declare function resolveFile(target: string): string;

package/types/skill.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Level gauge, as a bar or a circle.
+ *
+ * No JavaScript: the fill is done in CSS, and animates as it enters the
+ * viewport where `animation-timeline` exists. Elsewhere, the gauge is simply
+ * full — the value stays readable, which is what matters.
+ *
+ * @module @docpensieve/components/skill
+ */
+/** Shapes accepted by the gauge. */
+export declare const SKILL_SHAPES: readonly string[];
+/**
+ * Named gauge, from 0 to 100.
+ *
+ * @example
+ * <Skill name="Accessibility" level={80} />
+ * <Skill name="Accessibility" level={80} shape="circle" />
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any,
+ *   name?: any, level?: number, showValue?: boolean, shape?: string,
+ *   icon?: any, color?: string, label?: string,
+ * }} props `children` stands as a comment under the gauge. `showValue` hides
+ *   the numeric percentage without touching what the gauge announces.
+ *   `shape` picks between the bar and the circle. `icon` goes before the
+ *   name — a `LogoIcon` fits there. `color` tints the fill: any CSS colour,
+ *   the accent colour by default. `label` names the gauge for screen readers
+ *   when `name` is not text.
+ * @throws {DocPensieveError} Without a name, outside 0–100, or with an
+ *   unknown shape.
+ */
+export declare function Skill({ className, style, children, name, level, showValue, shape, icon, color, label, }: {
+    className?: string;
+    style?: object;
+    children?: any;
+    name?: any;
+    level?: number;
+    showValue?: boolean;
+    shape?: string;
+    icon?: any;
+    color?: string;
+    label?: string;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+}, HTMLElement>;

package/types/styles.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stylesheet of the shipped components.
+ *
+ * @module @docpensieve/components/styles
+ */
+/**
+ * Reads the default look of the components.
+ *
+ * It is concatenated with the theme's by the caller: a provider that
+ * redefines a slot replaces the `dp-*` class with its own, and these rules
+ * then stop applying by themselves.
+ *
+ * @returns {Promise<string>} CSS, trimmed.
+ * @throws {DocPensieveError} When the stylesheet is missing.
+ */
+export declare function componentsCss(): Promise<string>;

package/types/time-timer.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Conditional display by date or duration.
+ *
+ * **Mind the meaning on a static site**: “right now” means the moment of the
+ * **build**, not of reading. A page built in November will still show “the
+ * offer starts soon” in January if the site has not been rebuilt in between.
+ *
+ * This is not a flaw: it is what a time-based component becomes without
+ * client-side JavaScript. A scheduled build — a cron job in CI — is enough to
+ * keep it right.
+ *
+ * @module @docpensieve/components/time-timer
+ */
+/**
+ * Content shown before the period.
+ *
+ * No wrapper: a `span` around the author's content would become invalid
+ * markup as soon as they write a paragraph in it — which happens as soon as a
+ * blank line separates their text. The content therefore keeps its nature,
+ * inline or block.
+ *
+ * @param {{ children?: any, start?: string }} props
+ */
+export declare function FallbackBefore({ children }: {
+    children?: any;
+    start?: string;
+}): import("react").FunctionComponentElement<import("react").FragmentProps>;
+/**
+ * Content shown after the period.
+ *
+ * Without a wrapper, for the same reason as {@link FallbackBefore}.
+ *
+ * @param {{ children?: any, end?: string }} props
+ */
+export declare function FallbackAfter({ children }: {
+    children?: any;
+    end?: string;
+}): import("react").FunctionComponentElement<import("react").FragmentProps>;
+/**
+ * Shows its content during a period, with fallbacks before and after.
+ *
+ * @example
+ * <TimeTimer date="25/12/2025">
+ *   Merry Christmas
+ *   <FallbackBefore>It is not Christmas yet</FallbackBefore>
+ *   <FallbackAfter>Christmas is over</FallbackAfter>
+ * </TimeTimer>
+ *
+ * @param {{
+ *   date?: string, start?: string, duration?: string,
+ *   strict?: boolean, children?: any, now?: Date,
+ * }} props `now` only exists for tests: without it, the build moment stands.
+ */
+export declare function TimeTimer({ date, start, duration, strict, children, now }: {
+    date?: string;
+    start?: string;
+    duration?: string;
+    strict?: boolean;
+    children?: any;
+    now?: Date;
+}): any;

package/types/tooltip.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tooltip on hover and from the keyboard.
+ *
+ * No JavaScript: the bubble is a real element that CSS reveals on hover and
+ * on focus. The trigger is therefore reachable from the keyboard, and the
+ * bubble announced through `aria-describedby` rather than guessed.
+ *
+ * @module @docpensieve/components/tooltip
+ */
+/** Sides the bubble can sit on. */
+export declare const TOOLTIP_PLACEMENTS: readonly string[];
+/**
+ * Term with a tooltip.
+ *
+ * @example
+ * <Tooltip text="Generation of a complete site">build</Tooltip>
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any,
+ *   text?: string, placement?: string,
+ * }} props `text` is the content of the bubble; the children are the term it
+ *   explains.
+ * @throws {DocPensieveError} Without text, or with an unknown side.
+ */
+export declare function Tooltip({ className, style, children, text, placement }: {
+    className?: string;
+    style?: object;
+    children?: any;
+    text?: string;
+    placement?: string;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+}, HTMLElement>;

package/types/tree.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Collapsible tree.
+ *
+ * No JavaScript: expanding is the native behaviour of `<details>`, which
+ * works from the keyboard and stays printable.
+ *
+ * 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.
+ *
+ * @module @docpensieve/components/tree
+ */
+/**
+ * Root of a tree.
+ *
+ * @param {{ className?: string, style?: object, children?: any }} props
+ */
+export declare function Tree({ className, style, children }: {
+    className?: string;
+    style?: object;
+    children?: any;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<boolean>>;
+/**
+ * Entry of a tree.
+ *
+ * With children, it is a collapsible branch; without, a leaf. The difference
+ * is read from the writing, with no prop to set.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any,
+ *   label?: any, open?: boolean,
+ * }} props `open` expands the branch as soon as the page opens.
+ * @throws {DocPensieveError} Outside a `Tree`, or without a label.
+ */
+export declare function TreeItem({ className, style, children, label, open }: {
+    className?: string;
+    style?: object;
+    children?: any;
+    label?: any;
+    open?: boolean;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+}, HTMLElement>;