@misoto22/folio 0.0.0 → 0.17.0

package/dist/components/FloatingIconButton/FloatingIconButton.d.ts

@@ -0,0 +1,29 @@
+import * as react from 'react';
+import { ButtonHTMLAttributes, ReactNode } from 'react';
+
+interface FloatingIconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+    /**
+     * Which bottom corner the control is pinned to, in READING order —
+     * `end` is the right in English and the left in Arabic. Naming the sides
+     * `left`/`right` would have hard-coded one script's layout into the API.
+     */
+    position: 'start' | 'end';
+    /** Accessible name — the button has no visible text, so this is its only name. */
+    label: string;
+    children: ReactNode;
+}
+/**
+ * A round action pinned to a screen corner.
+ *
+ * A translucent paper ground with a backdrop blur rather than a drop shadow —
+ * the White Reset has no elevation ramp, so what separates the control from
+ * the page under it is the blur and the hairline, not a glow.
+ *
+ * @example
+ * <FloatingIconButton position="right" label="Back to top" onClick={scrollUp}>
+ *   <ArrowUp size={16} />
+ * </FloatingIconButton>
+ */
+declare function FloatingIconButton({ position, label, children, className, ...rest }: FloatingIconButtonProps): react.JSX.Element;
+
+export { FloatingIconButton, type FloatingIconButtonProps, FloatingIconButton as default };

package/dist/components/FloatingIconButton/FloatingIconButton.js

@@ -0,0 +1,34 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+import { warnBlankName } from "../../lib/warn.js";
+const POSITION_CLASS = { start: "bottom-20 start-6", end: "bottom-6 end-6" };
+function FloatingIconButton({
+  position,
+  label,
+  children,
+  className,
+  ...rest
+}) {
+  warnBlankName("FloatingIconButton", "label", label, 'the button is announced as "button" and nothing else');
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      "aria-label": label,
+      className: cn(
+        "fixed z-(--z-drawer) flex size-(--control-h-md) items-center justify-center rounded-(--radius-pill) border border-(--rule-2) bg-(--paper)/90 text-(--ink-2) backdrop-blur-sm transition-colors duration-(--duration-fast) hover:border-(--ink) hover:text-(--ink)",
+        POSITION_CLASS[position],
+        className
+      ),
+      ...rest,
+      children
+    }
+  );
+}
+var FloatingIconButton_default = FloatingIconButton;
+export {
+  FloatingIconButton,
+  FloatingIconButton_default as default
+};
+//# sourceMappingURL=FloatingIconButton.js.map

package/dist/components/FloatingIconButton/FloatingIconButton.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/FloatingIconButton/FloatingIconButton.tsx"],"sourcesContent":["'use client'\n\nimport type { ButtonHTMLAttributes, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\nimport { warnBlankName } from '../../lib/warn'\n\nexport interface FloatingIconButtonProps\n  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {\n  /**\n   * Which bottom corner the control is pinned to, in READING order —\n   * `end` is the right in English and the left in Arabic. Naming the sides\n   * `left`/`right` would have hard-coded one script's layout into the API.\n   */\n  position: 'start' | 'end'\n  /** Accessible name — the button has no visible text, so this is its only name. */\n  label: string\n  children: ReactNode\n}\n\n/**\n * Full literal class strings per corner. Tailwind only generates classes it can\n * see verbatim in the source, so the side is never interpolated into a string.\n *\n * The start corner sits higher: browser and OS chrome (a download shelf, a\n * status toast) commonly occupies the corner where reading begins, and the\n * global scroll action keeps the far one.\n */\nconst POSITION_CLASS = { start: 'bottom-20 start-6', end: 'bottom-6 end-6' } as const\n\n/**\n * A round action pinned to a screen corner.\n *\n * A translucent paper ground with a backdrop blur rather than a drop shadow —\n * the White Reset has no elevation ramp, so what separates the control from\n * the page under it is the blur and the hairline, not a glow.\n *\n * @example\n * <FloatingIconButton position=\"right\" label=\"Back to top\" onClick={scrollUp}>\n *   <ArrowUp size={16} />\n * </FloatingIconButton>\n */\nexport function FloatingIconButton({\n  position,\n  label,\n  children,\n  className,\n  ...rest\n}: FloatingIconButtonProps) {\n  warnBlankName('FloatingIconButton', 'label', label, 'the button is announced as \"button\" and nothing else')\n  return (\n    <button\n      type=\"button\"\n      aria-label={label}\n      className={cn(\n        'fixed z-(--z-drawer) flex size-(--control-h-md) items-center justify-center rounded-(--radius-pill) border border-(--rule-2) bg-(--paper)/90 text-(--ink-2) backdrop-blur-sm transition-colors duration-(--duration-fast) hover:border-(--ink) hover:text-(--ink)',\n        POSITION_CLASS[position],\n        className,\n      )}\n      {...rest}\n    >\n      {children}\n    </button>\n  )\n}\n\nexport default FloatingIconButton\n"],"mappings":";AAkDI;AA/CJ,SAAS,UAAU;AACnB,SAAS,qBAAqB;AAuB9B,MAAM,iBAAiB,EAAE,OAAO,qBAAqB,KAAK,iBAAiB;AAcpE,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAA4B;AAC1B,gBAAc,sBAAsB,SAAS,OAAO,sDAAsD;AAC1G,SACE;AAAA,IAAC;AAAA;AAAA,MACC,MAAK;AAAA,MACL,cAAY;AAAA,MACZ,WAAW;AAAA,QACT;AAAA,QACA,eAAe,QAAQ;AAAA,QACvB;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA;AAAA,EACH;AAEJ;AAEA,IAAO,6BAAQ;","names":[]}

package/dist/components/Heading/Heading.d.ts

@@ -0,0 +1,62 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * A step on the type ladder, named for the thing it heads.
+ *
+ * `title` is the top and there is nothing above it — a page has exactly one
+ * thing larger than its own records. `label` is not on the size ladder at all:
+ * it is the mono kicker, which is what a fifth-level heading should look like,
+ * because a serif heading three steps down is indistinguishable from bold body
+ * copy.
+ */
+type HeadingSize = 'title' | 'lead' | 'heading' | 'sub' | 'item' | 'label';
+interface HeadingProps extends HTMLAttributes<HTMLHeadingElement> {
+    children?: ReactNode;
+    /**
+     * The element: `1` renders `<h1>`, `6` renders `<h6>`.
+     *
+     * This is the document outline and nothing else — it is what a screen reader
+     * navigates by, so it follows the section the heading opens, never the size
+     * it wants to be. A heading two levels down inside an `<h2>` section is an
+     * `<h3>` even when the design calls for something enormous.
+     */
+    level: HeadingLevel;
+    /**
+     * The size, when the outline and the design genuinely disagree.
+     *
+     * Defaults from `level` through the ladder above, which is the answer nearly
+     * always. Reach for this when a semantically-correct `h3` opens a page and
+     * has to look like one — not to squeeze a fourth step between two that are
+     * already only 14% apart.
+     */
+    size?: HeadingSize;
+}
+/**
+ * A heading, with its element and its size decided separately.
+ *
+ * Every heading component that takes one number gets this wrong in one of two
+ * directions: either the outline is bent to reach a size (an `<h1>` in the
+ * middle of a page because the design wanted big type), or the size is bent to
+ * keep the outline (a section title set at 20px because it is the fourth level
+ * down). Both are one prop away from being right, so there are two.
+ *
+ * `level` is the document. `size` is the page. The default binds them through
+ * the system's ladder, so writing only `level` is correct — and the moment they
+ * come apart, the call site says so.
+ *
+ * Set in the editorial serif at weight 400, like every heading in the system.
+ * It also carries `scroll-margin-top`, so a heading given an `id` and linked
+ * from a table of contents comes to rest below the masthead rather than under
+ * it.
+ *
+ * @example
+ * <Heading level={1}>The White Reset</Heading>
+ * @example
+ * // Third level in the outline, page-title sized.
+ * <Heading level={3} size="title">Colour</Heading>
+ */
+declare function Heading({ children, level, size, className, ...rest }: HeadingProps): react.JSX.Element;
+
+export { Heading, type HeadingLevel, type HeadingProps, type HeadingSize, Heading as default };

package/dist/components/Heading/Heading.js

@@ -0,0 +1,44 @@
+import { jsx } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+const SIZE = {
+  title: "text-[length:var(--fs-title)] leading-[1.1] tracking-[-0.02em]",
+  lead: "text-[length:var(--fs-lead)] leading-[1.15] tracking-[-0.015em]",
+  heading: "text-[length:var(--fs-heading)] leading-[1.2]",
+  sub: "text-[length:var(--fs-sub)] leading-[1.25]",
+  item: "text-[length:var(--fs-item)] leading-[1.3]",
+  // Spelled out rather than reaching for the `eyebrow` utility: it and
+  // `font-heading` both set font-family, and a custom utility is invisible to
+  // tailwind-merge — so the two would land in the same cascade layer at the
+  // same specificity and source order would pick the winner.
+  label: "font-(family-name:--label-font) text-[11px] [text-transform:var(--label-case)] leading-[1.6] tracking-[calc(0.2em*var(--label-tracking-scale))] text-(--ink-3-aa)"
+};
+const LADDER = {
+  1: "title",
+  2: "heading",
+  3: "sub",
+  4: "item",
+  5: "label",
+  6: "label"
+};
+function Heading({ children, level, size, className, ...rest }) {
+  const Comp = `h${level}`;
+  const step = size ?? LADDER[level];
+  return /* @__PURE__ */ jsx(
+    Comp,
+    {
+      className: cn(
+        "m-0 scroll-mt-[var(--scroll-offset)] font-heading font-normal text-(--ink)",
+        SIZE[step],
+        className
+      ),
+      ...rest,
+      children
+    }
+  );
+}
+var Heading_default = Heading;
+export {
+  Heading,
+  Heading_default as default
+};
+//# sourceMappingURL=Heading.js.map

package/dist/components/Heading/Heading.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/Heading/Heading.tsx"],"sourcesContent":["import type { HTMLAttributes, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\n\nexport type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6\n\n/**\n * A step on the type ladder, named for the thing it heads.\n *\n * `title` is the top and there is nothing above it — a page has exactly one\n * thing larger than its own records. `label` is not on the size ladder at all:\n * it is the mono kicker, which is what a fifth-level heading should look like,\n * because a serif heading three steps down is indistinguishable from bold body\n * copy.\n */\nexport type HeadingSize = 'title' | 'lead' | 'heading' | 'sub' | 'item' | 'label'\n\nconst SIZE: Record<HeadingSize, string> = {\n  title: 'text-[length:var(--fs-title)] leading-[1.1] tracking-[-0.02em]',\n  lead: 'text-[length:var(--fs-lead)] leading-[1.15] tracking-[-0.015em]',\n  heading: 'text-[length:var(--fs-heading)] leading-[1.2]',\n  sub: 'text-[length:var(--fs-sub)] leading-[1.25]',\n  item: 'text-[length:var(--fs-item)] leading-[1.3]',\n  // Spelled out rather than reaching for the `eyebrow` utility: it and\n  // `font-heading` both set font-family, and a custom utility is invisible to\n  // tailwind-merge — so the two would land in the same cascade layer at the\n  // same specificity and source order would pick the winner.\n  label: 'font-(family-name:--label-font) text-[11px] [text-transform:var(--label-case)] leading-[1.6] tracking-[calc(0.2em*var(--label-tracking-scale))] text-(--ink-3-aa)',\n}\n\n/**\n * What each level looks like when nobody says otherwise — and the reason this\n * component exists rather than six styled tags.\n *\n * Read the gaps. `1 → title` then `2 → heading` SKIPS `lead`, because the\n * ladder's steps sit close together on purpose: it separates records of the\n * same kind, not a heading from its own sub-heading. `--fs-lead` over\n * `--fs-heading` is a ratio of 1.14 and reads as a rendering accident;\n * `--fs-title` over `--fs-heading` is 1.86 and reads as a hierarchy.\n *\n * So the correct pairing is what a caller gets for free, and stepping off the\n * ladder costs a prop and is visible in review. This is the same map\n * `article.css` applies to rendered Markdown, which is what makes a component\n * page and a post read as one publication.\n */\nconst LADDER: Record<HeadingLevel, HeadingSize> = {\n  1: 'title',\n  2: 'heading',\n  3: 'sub',\n  4: 'item',\n  5: 'label',\n  6: 'label',\n}\n\nexport interface HeadingProps extends HTMLAttributes<HTMLHeadingElement> {\n  children?: ReactNode\n  /**\n   * The element: `1` renders `<h1>`, `6` renders `<h6>`.\n   *\n   * This is the document outline and nothing else — it is what a screen reader\n   * navigates by, so it follows the section the heading opens, never the size\n   * it wants to be. A heading two levels down inside an `<h2>` section is an\n   * `<h3>` even when the design calls for something enormous.\n   */\n  level: HeadingLevel\n  /**\n   * The size, when the outline and the design genuinely disagree.\n   *\n   * Defaults from `level` through the ladder above, which is the answer nearly\n   * always. Reach for this when a semantically-correct `h3` opens a page and\n   * has to look like one — not to squeeze a fourth step between two that are\n   * already only 14% apart.\n   */\n  size?: HeadingSize\n}\n\n/**\n * A heading, with its element and its size decided separately.\n *\n * Every heading component that takes one number gets this wrong in one of two\n * directions: either the outline is bent to reach a size (an `<h1>` in the\n * middle of a page because the design wanted big type), or the size is bent to\n * keep the outline (a section title set at 20px because it is the fourth level\n * down). Both are one prop away from being right, so there are two.\n *\n * `level` is the document. `size` is the page. The default binds them through\n * the system's ladder, so writing only `level` is correct — and the moment they\n * come apart, the call site says so.\n *\n * Set in the editorial serif at weight 400, like every heading in the system.\n * It also carries `scroll-margin-top`, so a heading given an `id` and linked\n * from a table of contents comes to rest below the masthead rather than under\n * it.\n *\n * @example\n * <Heading level={1}>The White Reset</Heading>\n * @example\n * // Third level in the outline, page-title sized.\n * <Heading level={3} size=\"title\">Colour</Heading>\n */\nexport function Heading({ children, level, size, className, ...rest }: HeadingProps) {\n  const Comp = `h${level}` as const\n  const step = size ?? LADDER[level]\n\n  return (\n    <Comp\n      className={cn(\n        'm-0 scroll-mt-[var(--scroll-offset)] font-heading font-normal text-(--ink)',\n        SIZE[step],\n        className,\n      )}\n      {...rest}\n    >\n      {children}\n    </Comp>\n  )\n}\n\nexport default Heading\n"],"mappings":"AAwGI;AAvGJ,SAAS,UAAU;AAenB,MAAM,OAAoC;AAAA,EACxC,OAAO;AAAA,EACP,MAAM;AAAA,EACN,SAAS;AAAA,EACT,KAAK;AAAA,EACL,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA,EAKN,OAAO;AACT;AAiBA,MAAM,SAA4C;AAAA,EAChD,GAAG;AAAA,EACH,GAAG;AAAA,EACH,GAAG;AAAA,EACH,GAAG;AAAA,EACH,GAAG;AAAA,EACH,GAAG;AACL;AAgDO,SAAS,QAAQ,EAAE,UAAU,OAAO,MAAM,WAAW,GAAG,KAAK,GAAiB;AACnF,QAAM,OAAO,IAAI,KAAK;AACtB,QAAM,OAAO,QAAQ,OAAO,KAAK;AAEjC,SACE;AAAA,IAAC;AAAA;AAAA,MACC,WAAW;AAAA,QACT;AAAA,QACA,KAAK,IAAI;AAAA,QACT;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA;AAAA,EACH;AAEJ;AAEA,IAAO,kBAAQ;","names":[]}

package/dist/components/Input/Input.d.ts

@@ -0,0 +1,22 @@
+import * as react from 'react';
+import { InputHTMLAttributes, Ref } from 'react';
+
+interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+    /** Paints the resting border with `--danger` and reflects `aria-invalid`. */
+    invalid?: boolean;
+    ref?: Ref<HTMLInputElement>;
+}
+/**
+ * A single line of text entry.
+ *
+ * Shares `CONTROL_BASE` with Textarea and Select, so the three cannot drift
+ * apart. Pair with `Field` for the label, hint and error — an input with a
+ * placeholder and no label is not labelled, because the placeholder disappears
+ * the moment anyone types.
+ *
+ * @example
+ * <Field label="Email" htmlFor="email"><Input id="email" type="email" /></Field>
+ */
+declare function Input({ invalid, className, ref, 'aria-invalid': ariaInvalid, ...rest }: InputProps): react.JSX.Element;
+
+export { Input, type InputProps, Input as default };

package/dist/components/Input/Input.js

@@ -0,0 +1,21 @@
+import { jsx } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+import { CONTROL_BASE, CONTROL_BORDER, isInvalid } from "../../lib/control.js";
+function Input({ invalid, className, ref, "aria-invalid": ariaInvalid, ...rest }) {
+  const bad = isInvalid(invalid, ariaInvalid);
+  return /* @__PURE__ */ jsx(
+    "input",
+    {
+      ref,
+      "aria-invalid": ariaInvalid ?? (invalid ? true : void 0),
+      className: cn(CONTROL_BASE, bad ? CONTROL_BORDER.invalid : CONTROL_BORDER.resting, className),
+      ...rest
+    }
+  );
+}
+var Input_default = Input;
+export {
+  Input,
+  Input_default as default
+};
+//# sourceMappingURL=Input.js.map

package/dist/components/Input/Input.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/Input/Input.tsx"],"sourcesContent":["import type { InputHTMLAttributes, Ref } from 'react'\nimport { cn } from '../../lib/cn'\nimport { CONTROL_BASE, CONTROL_BORDER, isInvalid } from '../../lib/control'\n\nexport interface InputProps extends InputHTMLAttributes<HTMLInputElement> {\n  /** Paints the resting border with `--danger` and reflects `aria-invalid`. */\n  invalid?: boolean\n  ref?: Ref<HTMLInputElement>\n}\n\n/**\n * A single line of text entry.\n *\n * Shares `CONTROL_BASE` with Textarea and Select, so the three cannot drift\n * apart. Pair with `Field` for the label, hint and error — an input with a\n * placeholder and no label is not labelled, because the placeholder disappears\n * the moment anyone types.\n *\n * @example\n * <Field label=\"Email\" htmlFor=\"email\"><Input id=\"email\" type=\"email\" /></Field>\n */\nexport function Input({ invalid, className, ref, 'aria-invalid': ariaInvalid, ...rest }: InputProps) {\n  const bad = isInvalid(invalid, ariaInvalid)\n  return (\n    <input\n      ref={ref}\n      aria-invalid={ariaInvalid ?? (invalid ? true : undefined)}\n      className={cn(CONTROL_BASE, bad ? CONTROL_BORDER.invalid : CONTROL_BORDER.resting, className)}\n      {...rest}\n    />\n  )\n}\n\nexport default Input\n"],"mappings":"AAwBI;AAvBJ,SAAS,UAAU;AACnB,SAAS,cAAc,gBAAgB,iBAAiB;AAmBjD,SAAS,MAAM,EAAE,SAAS,WAAW,KAAK,gBAAgB,aAAa,GAAG,KAAK,GAAe;AACnG,QAAM,MAAM,UAAU,SAAS,WAAW;AAC1C,SACE;AAAA,IAAC;AAAA;AAAA,MACC;AAAA,MACA,gBAAc,gBAAgB,UAAU,OAAO;AAAA,MAC/C,WAAW,GAAG,cAAc,MAAM,eAAe,UAAU,eAAe,SAAS,SAAS;AAAA,MAC3F,GAAG;AAAA;AAAA,EACN;AAEJ;AAEA,IAAO,gBAAQ;","names":[]}

package/dist/components/Kbd/Kbd.d.ts

@@ -0,0 +1,27 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+interface KbdProps extends HTMLAttributes<HTMLElement> {
+    children: ReactNode;
+}
+/**
+ * A key on a keyboard, set as one.
+ *
+ * Renders a `<kbd>`, which is the element that means this — a `<span>` styled
+ * to look like a key tells a screen reader nothing. Sized in `em` so it tracks
+ * whatever type it sits beside rather than fixing itself at one px value, which
+ * is how the same shortcut ended up three different sizes across a page.
+ *
+ * Every dimension here tracked its context except the leading, which was a
+ * literal `1.6` — the body's READING leading, on a chip that is never a
+ * paragraph. Inside a control it therefore stood proud of the label beside it
+ * and pushed the whole box past its own height token: the masthead's search
+ * field measured 39px against a 36px `sm`, and it was this keycap doing it.
+ * `--control-lh` is the leading a one-line box gets, and this is one.
+ *
+ * @example
+ * Press <Kbd>⌘</Kbd> <Kbd>K</Kbd> to open the palette.
+ */
+declare function Kbd({ children, className, ...rest }: KbdProps): react.JSX.Element;
+
+export { Kbd, type KbdProps, Kbd as default };

package/dist/components/Kbd/Kbd.js

@@ -0,0 +1,21 @@
+import { jsx } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+function Kbd({ children, className, ...rest }) {
+  return /* @__PURE__ */ jsx(
+    "kbd",
+    {
+      className: cn(
+        "inline-flex min-w-[1.6em] items-center justify-center rounded-(--radius-sm) border border-(--rule-2) px-[0.4em] py-[0.1em] font-mono text-[0.8em] leading-(--control-lh) text-(--ink-2)",
+        className
+      ),
+      ...rest,
+      children
+    }
+  );
+}
+var Kbd_default = Kbd;
+export {
+  Kbd,
+  Kbd_default as default
+};
+//# sourceMappingURL=Kbd.js.map

package/dist/components/Kbd/Kbd.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/Kbd/Kbd.tsx"],"sourcesContent":["import type { HTMLAttributes, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\n\nexport interface KbdProps extends HTMLAttributes<HTMLElement> {\n  children: ReactNode\n}\n\n/**\n * A key on a keyboard, set as one.\n *\n * Renders a `<kbd>`, which is the element that means this — a `<span>` styled\n * to look like a key tells a screen reader nothing. Sized in `em` so it tracks\n * whatever type it sits beside rather than fixing itself at one px value, which\n * is how the same shortcut ended up three different sizes across a page.\n *\n * Every dimension here tracked its context except the leading, which was a\n * literal `1.6` — the body's READING leading, on a chip that is never a\n * paragraph. Inside a control it therefore stood proud of the label beside it\n * and pushed the whole box past its own height token: the masthead's search\n * field measured 39px against a 36px `sm`, and it was this keycap doing it.\n * `--control-lh` is the leading a one-line box gets, and this is one.\n *\n * @example\n * Press <Kbd>⌘</Kbd> <Kbd>K</Kbd> to open the palette.\n */\nexport function Kbd({ children, className, ...rest }: KbdProps) {\n  return (\n    <kbd\n      className={cn(\n        'inline-flex min-w-[1.6em] items-center justify-center rounded-(--radius-sm) border border-(--rule-2) px-[0.4em] py-[0.1em] font-mono text-[0.8em] leading-(--control-lh) text-(--ink-2)',\n        className,\n      )}\n      {...rest}\n    >\n      {children}\n    </kbd>\n  )\n}\n\nexport default Kbd\n"],"mappings":"AA2BI;AA1BJ,SAAS,UAAU;AAwBZ,SAAS,IAAI,EAAE,UAAU,WAAW,GAAG,KAAK,GAAa;AAC9D,SACE;AAAA,IAAC;AAAA;AAAA,MACC,WAAW;AAAA,QACT;AAAA,QACA;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA;AAAA,EACH;AAEJ;AAEA,IAAO,cAAQ;","names":[]}

package/dist/components/LinkArrow/LinkArrow.d.ts

@@ -0,0 +1,24 @@
+import * as react from 'react';
+import { HTMLAttributes } from 'react';
+
+/** The glyph itself, exported so a non-React surface can use the same mark. */
+declare const EXTERNAL_LINK_ARROW = "\u2197";
+type LinkArrowProps = HTMLAttributes<HTMLSpanElement>;
+/**
+ * The mark on a link that leaves the page — outbound, or on to a full index.
+ *
+ * Call sites used to write a bare `↗` inside the link text, which inherited the
+ * link's own size (a 17px arrow beside a 17px word, competing with it) and was
+ * read aloud as "north east arrow" because nothing hid it.
+ *
+ * `inline-block` is load-bearing twice over: it stops an underlined parent
+ * drawing its rule through the glyph, and it is what `align` is measured
+ * against. Sized in `em`, so it tracks whatever type it sits beside; coloured
+ * against paper, so a call site on a reversed plate passes its own colour.
+ *
+ * @example
+ * <a href="https://example.com">Read the paper<LinkArrow /></a>
+ */
+declare function LinkArrow({ className, ...rest }: LinkArrowProps): react.JSX.Element;
+
+export { EXTERNAL_LINK_ARROW, LinkArrow, type LinkArrowProps, LinkArrow as default };

package/dist/components/LinkArrow/LinkArrow.js

@@ -0,0 +1,24 @@
+import { jsx } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+const EXTERNAL_LINK_ARROW = "\u2197";
+function LinkArrow({ className, ...rest }) {
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      "aria-hidden": "true",
+      className: cn(
+        "ms-[0.22em] inline-block align-[0.28em] font-mono text-[0.68em] leading-none text-(--ink-3-aa)",
+        className
+      ),
+      ...rest,
+      children: EXTERNAL_LINK_ARROW
+    }
+  );
+}
+var LinkArrow_default = LinkArrow;
+export {
+  EXTERNAL_LINK_ARROW,
+  LinkArrow,
+  LinkArrow_default as default
+};
+//# sourceMappingURL=LinkArrow.js.map

package/dist/components/LinkArrow/LinkArrow.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/LinkArrow/LinkArrow.tsx"],"sourcesContent":["import type { HTMLAttributes } from 'react'\nimport { cn } from '../../lib/cn'\n\n/** The glyph itself, exported so a non-React surface can use the same mark. */\nexport const EXTERNAL_LINK_ARROW = '↗'\n\nexport type LinkArrowProps = HTMLAttributes<HTMLSpanElement>\n\n/**\n * The mark on a link that leaves the page — outbound, or on to a full index.\n *\n * Call sites used to write a bare `↗` inside the link text, which inherited the\n * link's own size (a 17px arrow beside a 17px word, competing with it) and was\n * read aloud as \"north east arrow\" because nothing hid it.\n *\n * `inline-block` is load-bearing twice over: it stops an underlined parent\n * drawing its rule through the glyph, and it is what `align` is measured\n * against. Sized in `em`, so it tracks whatever type it sits beside; coloured\n * against paper, so a call site on a reversed plate passes its own colour.\n *\n * @example\n * <a href=\"https://example.com\">Read the paper<LinkArrow /></a>\n */\nexport function LinkArrow({ className, ...rest }: LinkArrowProps) {\n  return (\n    <span\n      aria-hidden=\"true\"\n      className={cn(\n        'ms-[0.22em] inline-block align-[0.28em] font-mono text-[0.68em] leading-none text-(--ink-3-aa)',\n        className,\n      )}\n      {...rest}\n    >\n      {EXTERNAL_LINK_ARROW}\n    </span>\n  )\n}\n\nexport default LinkArrow\n"],"mappings":"AAyBI;AAxBJ,SAAS,UAAU;AAGZ,MAAM,sBAAsB;AAmB5B,SAAS,UAAU,EAAE,WAAW,GAAG,KAAK,GAAmB;AAChE,SACE;AAAA,IAAC;AAAA;AAAA,MACC,eAAY;AAAA,MACZ,WAAW;AAAA,QACT;AAAA,QACA;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA;AAAA,EACH;AAEJ;AAEA,IAAO,oBAAQ;","names":[]}

package/dist/components/Markdown/Markdown.d.ts

@@ -0,0 +1,139 @@
+import * as react from 'react';
+import { MarkdownHeadingLevel, MarkdownNode } from './nodes.js';
+export { MarkdownInline } from './nodes.js';
+export { parseMarkdown } from './parse.js';
+export { slugify } from './slug.js';
+
+interface MarkdownProps {
+    /** The Markdown source. A string — not nodes, not HTML. */
+    children: string;
+    /**
+     * The level the document's top heading renders at.
+     *
+     * Markdown is written as a document, so its `#` is an `<h1>`. Dropped into a
+     * page that already has one — inside an `<h2>` section, in a card, under a
+     * dialog's title — that produces two first-level headings and an outline a
+     * screen reader cannot navigate. Set this to the level BELOW the heading the
+     * content sits under, and every level in the document shifts with it.
+     */
+    headingLevelStart?: MarkdownHeadingLevel;
+    /**
+     * Namespaces the generated heading ids.
+     *
+     * Two documents on one page both containing "Installation" would otherwise
+     * both claim `#installation`, and a fragment link would land on whichever the
+     * browser found first.
+     */
+    idPrefix?: string;
+    /**
+     * Adds the system's outbound arrow to links that leave for another site.
+     *
+     * Off by default, and opt-in rather than automatic for two reasons. The mark
+     * is an addition to a sentence the component did not write, which is a
+     * different kind of act from styling one. And `Markdown` has no idea what
+     * origin it is being rendered on, so "leaves for another site" can only mean
+     * "carries an `http`/`https` scheme" — an absolute link back to your own
+     * domain gets the arrow too. A caller who knows the shape of their content
+     * turns it on; one who does not should not have it turned on for them.
+     *
+     * The `rel` on an outbound link is NOT opt-in and cannot be turned off: it
+     * is the security half of the same boundary as the scheme check.
+     */
+    markExternalLinks?: boolean;
+    /**
+     * Bring your own parser.
+     *
+     * Anything that turns the source into `MarkdownNode`s: markdown-it, remark,
+     * or a pipeline that already has an AST and only needs mapping. The node
+     * shapes are exported alongside the component as `MarkdownNode`,
+     * `MarkdownInline` and `MarkdownHeadingLevel`. The built-in parser covers the
+     * subset this system styles; this is the seam for tables, footnotes, task
+     * lists and everything else.
+     */
+    parse?: (source: string) => MarkdownNode[];
+}
+/**
+ * A Markdown string, rendered as this system's components.
+ *
+ * The gap it fills is content nobody on this side wrote: a comment, a README, a
+ * model's answer, a description out of a database. `Article` cannot take those
+ * — it renders HTML through `dangerouslySetInnerHTML` and is documented as
+ * trusted-input-only — and until now the alternative was a `<pre>` or a
+ * sanitiser bolted onto a styling primitive.
+ *
+ * IT IS NOT AN `Article`, and the two do not merge. `Markdown` turns a string
+ * into nodes; `Article` is the reading column those nodes can sit in. It
+ * renders a FRAGMENT rather than a wrapper, which is what makes that nesting
+ * work — `Article`'s rhythm is a direct-child combinator, so any element
+ * between the two, `display: contents` included, would cost every paragraph
+ * its spacing.
+ *
+ * ── It brings type and colour, and no vertical rhythm ──
+ *
+ * The nodes carry the system's faces and inks on their own, so one of these
+ * looks right in isolation. It is not SPACED in isolation: every node renders
+ * `m-0`, and a fragment has no box of its own to put a gap in. Nor does a
+ * uniform `gap` on a container reproduce it, because prose spacing is not
+ * uniform — `article.css` gives a heading 2.25em above and 0.75em below, which
+ * is what sits a heading with the paragraph it introduces rather than midway
+ * between two. For anything longer than a sentence — a comment, an answer, a
+ * README — put it in `<Article as="div">` and get the real rhythm for the cost
+ * of one element.
+ *
+ * ── A fenced code block brings a client component with it ──
+ *
+ * The renderer is plain functions and has no state, but a fenced block renders
+ * `CodeBlock`, which is `'use client'` and arrives with `useState`,
+ * `useEffect` and two icons. That is correct — the copy button is the reason
+ * the block exists — but "server-rendered" only holds for content with no code
+ * in it, which is worth knowing before this goes into a route that has no
+ * client bundle yet.
+ *
+ * ── Why there is no parser in `dependencies` ──
+ *
+ * Three options, and the decision is written here because it is the one a
+ * reader will want to argue with.
+ *
+ *  1. BUNDLE A PARSER. markdown-it is the obvious pick, and the documentation
+ *     site already depends on it — but the site is an app and this is a
+ *     library, where the dependency list is part of the contract every consumer
+ *     signs. Measured with the same esbuild pass `check:size` uses, markdown-it
+ *     is 110.7 kB minified against the 38.9 kB this package had left under its
+ *     bundle budget. It is not close, and "we will raise the budget" is how a
+ *     design system becomes the largest thing on a page.
+ *  2. TAKE PRE-PARSED HTML, the way `Article` does. Cheapest, and wrong for the
+ *     case this exists for: HTML from an untrusted author is the input this is
+ *     supposed to make safe, and it cannot carry `headingLevelStart` or stable
+ *     heading ids without the component parsing markup back apart to find them.
+ *  3. PARSE THE SUBSET WE STYLE, and take a `parse` function for the rest.
+ *     Chosen. The block grammar is line-based and small (see `parse.ts`), it
+ *     emits React elements rather than markup — so there is no
+ *     `dangerouslySetInnerHTML` in this path at all, no sanitiser to configure
+ *     and no sanitiser to get wrong — and a consumer who needs tables,
+ *     footnotes or task lists passes `parse` and keeps every other promise the
+ *     component makes.
+ *
+ * Headings carry an `id` slugged from their own text and deduplicated within
+ * the document, so a table of contents can link to them without the caller
+ * post-processing the DOM to find out where they went.
+ *
+ * A link in the source is validated here, at the boundary: a scheme that is not
+ * `http`, `https`, `mailto` or `tel` never becomes a link, and one that leaves
+ * for another site carries `rel="noreferrer nofollow"` — so an author the page
+ * does not trust cannot spend its ranking or read its URL out of the `Referer`.
+ *
+ * @example
+ * // A comment body or an answer: the reading column is what spaces it.
+ * <Article as="div">
+ *   <Markdown headingLevelStart={3} idPrefix="answer">{answer}</Markdown>
+ * </Article>
+ * @example
+ * // A whole document, in the column it was written for.
+ * <Article><Markdown>{readme}</Markdown></Article>
+ * @example
+ * // Tables and footnotes, via the consumer's own pipeline.
+ * <Markdown parse={(source) => toMarkdownNodes(md.parse(source, {}))}>{post}</Markdown>
+ */
+declare function Markdown({ children, headingLevelStart, idPrefix, markExternalLinks, parse, }: MarkdownProps): react.JSX.Element;
+
+export { Markdown, MarkdownHeadingLevel, MarkdownNode, type MarkdownProps, Markdown as default };

package/dist/components/Markdown/Markdown.js

@@ -0,0 +1,135 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
+import { Code } from "../Code/Code.js";
+import { CodeBlock } from "../CodeBlock/CodeBlock.js";
+import { Heading } from "../Heading/Heading.js";
+import { LinkArrow } from "../LinkArrow/LinkArrow.js";
+import { Separator } from "../Separator/Separator.js";
+import { Text } from "../Text/Text.js";
+import { isOutbound } from "./inline.js";
+import { parseMarkdown } from "./parse.js";
+import { slugify } from "./slug.js";
+import { parseMarkdown as parseMarkdown2 } from "./parse.js";
+import { slugify as slugify2 } from "./slug.js";
+function textOf(nodes) {
+  return nodes.map((node) => {
+    if (node.type === "text" || node.type === "code") return node.value;
+    if (node.type === "image") return node.alt;
+    return textOf(node.children);
+  }).join("");
+}
+function headingId(text, context) {
+  const base = slugify(text) || "section";
+  const seen = (context.taken.get(base) ?? 0) + 1;
+  context.taken.set(base, seen);
+  const id = seen === 1 ? base : `${base}-${seen}`;
+  return context.idPrefix ? `${context.idPrefix}-${id}` : id;
+}
+function renderInline(node, key, context) {
+  switch (node.type) {
+    case "text":
+      return node.value;
+    case "code":
+      return /* @__PURE__ */ jsx(Code, { children: node.value }, key);
+    case "strong":
+      return /* @__PURE__ */ jsx("strong", { className: "font-medium text-(--ink)", children: node.children.map((child, index) => renderInline(child, index, context)) }, key);
+    case "emphasis":
+      return /* @__PURE__ */ jsx("em", { className: "italic", children: node.children.map((child, index) => renderInline(child, index, context)) }, key);
+    case "image":
+      return /* @__PURE__ */ jsx(
+        "img",
+        {
+          src: node.src,
+          alt: node.alt,
+          loading: "lazy",
+          className: "h-auto max-w-full rounded-(--radius)"
+        },
+        key
+      );
+    case "link": {
+      const outbound = isOutbound(node.href);
+      return /* @__PURE__ */ jsxs(
+        "a",
+        {
+          href: node.href,
+          rel: outbound ? "noreferrer nofollow" : void 0,
+          className: "text-(--ink) underline decoration-[var(--rule-2)] underline-offset-4 transition-[text-decoration-color] duration-(--duration-fast) hover:decoration-[var(--ink)]",
+          children: [
+            node.children.map((child, index) => renderInline(child, index, context)),
+            outbound && context.markExternalLinks ? /* @__PURE__ */ jsx(LinkArrow, {}) : null
+          ]
+        },
+        key
+      );
+    }
+  }
+}
+function renderItem(blocks, key, context) {
+  const first = blocks[0];
+  const only = blocks.length === 1 && first?.type === "paragraph" ? first : void 0;
+  return /* @__PURE__ */ jsx("li", { className: "relative", children: only ? only.children.map((child, i) => renderInline(child, i, context)) : blocks.map((block, i) => renderBlock(block, i, context)) }, key);
+}
+function renderBlock(node, key, context) {
+  switch (node.type) {
+    case "heading": {
+      const level = Math.min(6, node.level + context.headingLevelStart - 1);
+      return /* @__PURE__ */ jsx(Heading, { level, id: headingId(textOf(node.children), context), children: node.children.map((child, index) => renderInline(child, index, context)) }, key);
+    }
+    case "paragraph":
+      return /* @__PURE__ */ jsx(Text, { children: node.children.map((child, index) => renderInline(child, index, context)) }, key);
+    case "code":
+      return /* @__PURE__ */ jsx(CodeBlock, { code: node.value, lang: node.lang }, key);
+    case "rule":
+      return /* @__PURE__ */ jsx(Separator, { weight: "edge", decorative: false }, key);
+    case "quote":
+      return /* @__PURE__ */ jsx(
+        "blockquote",
+        {
+          className: "m-0 border-s-2 border-(--rule-hard) ps-[1.25em] font-serif text-[length:var(--fs-item)] leading-[1.55] text-(--ink) [&>*+*]:mt-[0.6em]",
+          children: node.children.map((child, i) => renderBlock(child, i, context))
+        },
+        key
+      );
+    case "list":
+      return node.ordered ? /* @__PURE__ */ jsx(
+        "ol",
+        {
+          className: "m-0 list-decimal ps-[1.4em] text-(--ink-2) marker:text-(--ink-3-aa) [&>li+li]:mt-[0.4em]",
+          children: node.items.map((item, i) => renderItem(item, i, context))
+        },
+        key
+      ) : (
+        // The marker is a hairline dash drawn on `::before`, not a disc: the
+        // system's only filled circle is a status dot. `article.css` draws the
+        // same dash on the same pseudo-element, so markdown dropped into an
+        // Article coincides with the stylesheet rather than doubling it.
+        /* @__PURE__ */ jsx(
+          "ul",
+          {
+            className: "m-0 list-none ps-[1.15em] text-(--ink-2) [&>li+li]:mt-[0.4em] [&>li]:before:absolute [&>li]:before:start-[-1.15em] [&>li]:before:top-[0.85em] [&>li]:before:h-px [&>li]:before:w-[0.55em] [&>li]:before:bg-(--rule-2) [&>li]:before:content-['']",
+            children: node.items.map((item, i) => renderItem(item, i, context))
+          },
+          key
+        )
+      );
+  }
+}
+function Markdown({
+  children,
+  headingLevelStart = 1,
+  idPrefix,
+  markExternalLinks = false,
+  parse = parseMarkdown
+}) {
+  const context = { headingLevelStart, idPrefix, markExternalLinks, taken: /* @__PURE__ */ new Map() };
+  const nodes = typeof children === "string" ? parse(children) : [];
+  return /* @__PURE__ */ jsx(Fragment, { children: nodes.map((node, index) => renderBlock(node, index, context)) });
+}
+var Markdown_default = Markdown;
+export {
+  Markdown,
+  Markdown_default as default,
+  parseMarkdown2 as parseMarkdown,
+  slugify2 as slugify
+};
+//# sourceMappingURL=Markdown.js.map