@misoto22/design 0.7.0 → 0.9.0

package/dist/components/Field/Field.js

@@ -3,12 +3,16 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { Label } from "@radix-ui/react-label";
 import { cloneElement, isValidElement, useId } from "react";
 import { cn } from "../../lib/cn.js";
+import { DEV, warn } from "../../lib/warn.js";
+import { FieldControlProvider } from "./field-control.js";
 function Field({
   label,
   htmlFor,
+  description,
   hint,
   error,
   required,
+  layout = "stacked",
   children,
   className,
   ...rest
@@ -17,33 +21,70 @@ function Field({
   const controlId = htmlFor ?? generatedId;
   const message = error ?? hint;
   const messageId = message != null ? `${controlId}-${error != null ? "error" : "hint"}` : void 0;
+  const descriptionId = description != null ? `${controlId}-description` : void 0;
+  const labelId = label != null ? `${controlId}-label` : void 0;
   let control = children;
   if (isValidElement(children)) {
     const child = children;
     control = cloneElement(child, {
       id: child.props.id ?? controlId,
-      "aria-describedby": [child.props["aria-describedby"], messageId].filter(Boolean).join(" ") || void 0,
+      "aria-describedby": [child.props["aria-describedby"], descriptionId, messageId].filter(Boolean).join(" ") || void 0,
       "aria-required": required || child.props["aria-required"] || void 0,
       "aria-invalid": error != null ? child.props["aria-invalid"] ?? true : child.props["aria-invalid"]
     });
+  } else if (DEV) {
+    warn({
+      code: "FIELD_CONTROL_NOT_WIRED",
+      problem: "Field's child is not a single React element, so the label, aria-describedby, aria-required and aria-invalid were not applied to any control.",
+      field: "children",
+      fix: "Put exactly one control element directly inside Field. For a row of controls, give each its own Field and lay them out around it.",
+      component: "Field"
+    });
   }
-  return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col gap-1.5", className), ...rest, children: [
-    label != null && /* @__PURE__ */ jsxs(Label, { htmlFor: controlId, className: "text-sm text-(--ink)", children: [
+  if (DEV && isValidElement(children) && typeof children.type === "string") {
+    const LABELLABLE = ["input", "select", "textarea", "button", "meter", "output", "progress"];
+    if (!LABELLABLE.includes(children.type)) {
+      warn({
+        code: "FIELD_CONTROL_NOT_LABELLABLE",
+        problem: `Field's child is a <${children.type}>, which cannot take a label \u2014 so the id, aria-describedby, aria-required and aria-invalid were applied to it rather than to a control.`,
+        field: "children",
+        fix: "Put the control itself directly inside Field, with no wrapper. For a row of controls, give each its own Field and lay them out around it.",
+        component: "Field"
+      });
+    }
+  }
+  const wired = /* @__PURE__ */ jsx(FieldControlProvider, { value: { labelId }, children: control });
+  const heading = (label != null || description != null) && /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1", children: [
+    label != null && /* @__PURE__ */ jsxs(Label, { id: labelId, htmlFor: controlId, className: "text-sm text-(--ink)", children: [
       label,
       required && /* @__PURE__ */ jsxs("span", { className: "text-(--danger)", "aria-hidden": "true", children: [
         " ",
         "*"
       ] })
     ] }),
-    control,
-    message != null && /* @__PURE__ */ jsx(
-      "p",
-      {
-        id: messageId,
-        className: cn("m-0 text-xs", error != null ? "text-(--danger)" : "text-(--ink-3-aa)"),
-        children: message
-      }
-    )
+    description != null && /* @__PURE__ */ jsx("p", { id: descriptionId, className: "m-0 text-xs text-(--ink-3-aa)", children: description })
+  ] });
+  const note = message != null && /* @__PURE__ */ jsx(
+    "p",
+    {
+      id: messageId,
+      className: cn("m-0 text-xs", error != null ? "text-(--danger)" : "text-(--ink-3-aa)"),
+      children: message
+    }
+  );
+  if (layout === "row") {
+    return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col gap-1.5", className), ...rest, children: [
+      /* @__PURE__ */ jsxs("div", { className: "flex items-start justify-between gap-6", children: [
+        /* @__PURE__ */ jsx("div", { className: "min-w-0 flex-1", children: heading }),
+        /* @__PURE__ */ jsx("div", { className: "shrink-0", children: wired })
+      ] }),
+      note
+    ] });
+  }
+  return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col gap-1.5", className), ...rest, children: [
+    heading,
+    wired,
+    note
   ] });
 }
 var Field_default = Field;

package/dist/components/Field/Field.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/components/Field/Field.tsx"],"sourcesContent":["'use client'\n\nimport { Label } from '@radix-ui/react-label'\nimport { cloneElement, isValidElement, useId } from 'react'\nimport type { HTMLAttributes, ReactElement, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\n\nexport interface FieldProps extends HTMLAttributes<HTMLDivElement> {\n  /** Visible label text; renders a `--danger` asterisk when `required`. */\n  label?: ReactNode\n  /**\n   * The control's `id`. Optional: when omitted, the field generates one and\n   * puts it on the control child itself, so the label still points at\n   * something. Pass it explicitly when the id has to be stable across renders\n   * — a form library referencing it by name, say.\n   */\n  htmlFor?: string\n  /** Helper copy shown below the control when there is no `error`. */\n  hint?: ReactNode\n  /** Validation message; takes precedence over `hint` when present. */\n  error?: ReactNode\n  required?: boolean\n  children: ReactNode\n}\n\ntype WirableControl = ReactElement<{\n  id?: string\n  'aria-describedby'?: string\n  'aria-required'?: boolean\n  'aria-invalid'?: boolean | 'true' | 'false'\n}>\n\n/**\n * A labelled form row: label, control, and the one message below it.\n *\n * The visible message is only half of accessible validation — it must also\n * reach the control. This wires `aria-describedby`, `aria-required` and\n * `aria-invalid` onto the single control child so the requirement and the error\n * are announced, not merely drawn (WCAG 1.3.1 / 3.3.1 / 4.1.2).\n *\n * An earlier version derived the message id from `htmlFor`, which meant a\n * caller who left `htmlFor` off got a hint that was rendered and never\n * announced — the failure was invisible in the browser and total for a screen\n * reader. The id is now generated when it is not supplied.\n *\n * `hint` and `error` are one slot, not two stacked messages: when a field is\n * wrong, the thing to read is what is wrong with it.\n *\n * @example\n * <Field label=\"Email\" required hint=\"We never share it.\"><Input type=\"email\" /></Field>\n * @example\n * <Field label=\"Name\" error=\"Name is required.\"><Input /></Field>\n */\nexport function Field({\n  label,\n  htmlFor,\n  hint,\n  error,\n  required,\n  children,\n  className,\n  ...rest\n}: FieldProps) {\n  const generatedId = useId()\n  const controlId = htmlFor ?? generatedId\n  const message = error ?? hint\n  const messageId = message != null ? `${controlId}-${error != null ? 'error' : 'hint'}` : undefined\n\n  let control = children\n  if (isValidElement(children)) {\n    const child = children as WirableControl\n    control = cloneElement(child, {\n      id: child.props.id ?? controlId,\n      'aria-describedby':\n        [child.props['aria-describedby'], messageId].filter(Boolean).join(' ') || undefined,\n      'aria-required': required || child.props['aria-required'] || undefined,\n      'aria-invalid':\n        error != null ? (child.props['aria-invalid'] ?? true) : child.props['aria-invalid'],\n    })\n  }\n\n  return (\n    <div className={cn('flex flex-col gap-1.5', className)} {...rest}>\n      {label != null && (\n        <Label htmlFor={controlId} className=\"text-sm text-(--ink)\">\n          {label}\n          {required && (\n            <span className=\"text-(--danger)\" aria-hidden=\"true\">\n              {' '}\n              *\n            </span>\n          )}\n        </Label>\n      )}\n      {control}\n      {message != null && (\n        <p\n          id={messageId}\n          className={cn('m-0 text-xs', error != null ? 'text-(--danger)' : 'text-(--ink-3-aa)')}\n        >\n          {message}\n        </p>\n      )}\n    </div>\n  )\n}\n\nexport default Field\n"],"mappings":";AAuFY,SASJ,KATI;AArFZ,SAAS,aAAa;AACtB,SAAS,cAAc,gBAAgB,aAAa;AAEpD,SAAS,UAAU;AAgDZ,SAAS,MAAM;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAe;AACb,QAAM,cAAc,MAAM;AAC1B,QAAM,YAAY,WAAW;AAC7B,QAAM,UAAU,SAAS;AACzB,QAAM,YAAY,WAAW,OAAO,GAAG,SAAS,IAAI,SAAS,OAAO,UAAU,MAAM,KAAK;AAEzF,MAAI,UAAU;AACd,MAAI,eAAe,QAAQ,GAAG;AAC5B,UAAM,QAAQ;AACd,cAAU,aAAa,OAAO;AAAA,MAC5B,IAAI,MAAM,MAAM,MAAM;AAAA,MACtB,oBACE,CAAC,MAAM,MAAM,kBAAkB,GAAG,SAAS,EAAE,OAAO,OAAO,EAAE,KAAK,GAAG,KAAK;AAAA,MAC5E,iBAAiB,YAAY,MAAM,MAAM,eAAe,KAAK;AAAA,MAC7D,gBACE,SAAS,OAAQ,MAAM,MAAM,cAAc,KAAK,OAAQ,MAAM,MAAM,cAAc;AAAA,IACtF,CAAC;AAAA,EACH;AAEA,SACE,qBAAC,SAAI,WAAW,GAAG,yBAAyB,SAAS,GAAI,GAAG,MACzD;AAAA,aAAS,QACR,qBAAC,SAAM,SAAS,WAAW,WAAU,wBAClC;AAAA;AAAA,MACA,YACC,qBAAC,UAAK,WAAU,mBAAkB,eAAY,QAC3C;AAAA;AAAA,QAAI;AAAA,SAEP;AAAA,OAEJ;AAAA,IAED;AAAA,IACA,WAAW,QACV;AAAA,MAAC;AAAA;AAAA,QACC,IAAI;AAAA,QACJ,WAAW,GAAG,eAAe,SAAS,OAAO,oBAAoB,mBAAmB;AAAA,QAEnF;AAAA;AAAA,IACH;AAAA,KAEJ;AAEJ;AAEA,IAAO,gBAAQ;","names":[]}
+{"version":3,"sources":["../../../src/components/Field/Field.tsx"],"sourcesContent":["'use client'\n\nimport { Label } from '@radix-ui/react-label'\nimport { cloneElement, isValidElement, useId } from 'react'\nimport type { HTMLAttributes, ReactElement, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\nimport { DEV, warn } from '../../lib/warn'\nimport { FieldControlProvider } from './field-control'\n\n/**\n * Where the control sits relative to its label.\n *\n * `stacked` is the form row: label, control, message, down the page.\n *\n * `row` is the settings row: the label and its `description` in a column at the\n * inline start, the control at the inline end, one rhythm down a settings\n * screen. It is a layout, not a second component — the label wiring, the\n * required marker and the message slot are the same three things either way,\n * and a `SettingRow` beside this would be all three of them written twice.\n */\nexport type FieldLayout = 'stacked' | 'row'\n\nexport interface FieldProps extends HTMLAttributes<HTMLDivElement> {\n  /** Visible label text; renders a `--danger` asterisk when `required`. */\n  label?: ReactNode\n  /**\n   * The control's `id`. Optional: when omitted, the field generates one and\n   * puts it on the control child itself, so the label still points at\n   * something. Pass it explicitly when the id has to be stable across renders\n   * — a form library referencing it by name, say.\n   */\n  htmlFor?: string\n  /**\n   * A second line under the LABEL, explaining what the setting does.\n   *\n   * Distinct from `hint`, which sits under the control and belongs to the input\n   * — \"We never share it\". This belongs to the thing being switched on, and it\n   * is what makes a settings row a settings row. Both reach the control through\n   * `aria-describedby`, so a row that has a description and an error announces\n   * both.\n   */\n  description?: ReactNode\n  /** Helper copy shown below the control when there is no `error`. */\n  hint?: ReactNode\n  /** Validation message; takes precedence over `hint` when present. */\n  error?: ReactNode\n  required?: boolean\n  /** Where the control sits relative to its label. See {@link FieldLayout}. */\n  layout?: FieldLayout\n  children: ReactNode\n}\n\ntype WirableControl = ReactElement<{\n  id?: string\n  'aria-describedby'?: string\n  'aria-required'?: boolean\n  'aria-invalid'?: boolean | 'true' | 'false'\n}>\n\n/**\n * A labelled form row: label, control, and the one message below it.\n *\n * The visible message is only half of accessible validation — it must also\n * reach the control. This wires `aria-describedby`, `aria-required` and\n * `aria-invalid` onto the single control child so the requirement and the error\n * are announced, not merely drawn (WCAG 1.3.1 / 3.3.1 / 4.1.2).\n *\n * An earlier version derived the message id from `htmlFor`, which meant a\n * caller who left `htmlFor` off got a hint that was rendered and never\n * announced — the failure was invisible in the browser and total for a screen\n * reader. The id is now generated when it is not supplied.\n *\n * `hint` and `error` are one slot, not two stacked messages: when a field is\n * wrong, the thing to read is what is wrong with it. `description` is a\n * different slot again — it explains the SETTING, not the input, and it is what\n * `layout=\"row\"` puts under the label to make a settings row.\n *\n * **How the wiring reaches the control.** `cloneElement` puts the four\n * attributes on the single child, and each control forwards them to whatever\n * element carries the role — which is the child itself for `Input`, `Textarea`,\n * `NativeSelect`, `Checkbox`, `Switch` and any host element written by hand, and\n * a trigger, a group or a thumb further down for `Select`, `Combobox`,\n * `DatePicker`, `Slider`, `RadioGroup` and `ToggleGroup`. The composites used to\n * drop them on the floor, which drew a hint under a control that never announced\n * it; a wrapper that appears to wire things up and does not is worse than one\n * that never claimed to.\n *\n * The label's own id travels separately, through context, because a name is the\n * one thing a prop cannot carry: a trigger whose text is its VALUE is named by\n * the label AND by itself, so `<Field label=\"Region\"><Select/></Field>`\n * announces \"Region, Australia\" rather than either half.\n *\n * Three things stay out of reach, and each of them is the control's own markup\n * rather than a gap in this wiring. A `<label for>` binds only to a labellable\n * element, so the words do not click through to a `RadioGroup`, a `ToggleGroup`\n * or a `Slider`: the first two are a `role=\"radiogroup\"` named by pointing back\n * at the label instead, exactly as a `<legend>` is, and the third carries\n * `role=\"slider\"` on a thumb below a roleless root. `required` reaches a control\n * as `aria-required`, which `DatePicker`'s plain `<button>` trigger and a\n * multiple-value `ToggleGroup`'s `role=\"toolbar\"` have nowhere to put; there the\n * asterisk is the only marker. And `aria-invalid` reaches `Slider`'s root rather\n * than its thumb, so an errored slider is drawn wrong without being announced\n * wrong.\n *\n * Each composite still takes its own `label` prop — that is what names it\n * standing outside a field, and `Select`, `Combobox` and `DatePicker` warn when\n * it is blank. It is no longer used INSTEAD of this one's.\n *\n * What no wiring can reach, the field says out loud in development rather than\n * failing silently: `FIELD_CONTROL_NOT_LABELLABLE` when the child is a host\n * element a label cannot bind to — the `<div>` wrapper that takes the id and\n * leaves the control inside it with nothing — and `FIELD_CONTROL_NOT_WIRED`\n * when there is no single element to wire at all.\n *\n * @example\n * <Field label=\"Email\" required hint=\"We never share it.\"><Input type=\"email\" /></Field>\n * @example\n * <Field label=\"Name\" error=\"Name is required.\"><Input /></Field>\n * @example\n * <Field layout=\"row\" label=\"Email notifications\" description=\"A digest every Monday.\">\n *   <Switch defaultChecked />\n * </Field>\n */\nexport function Field({\n  label,\n  htmlFor,\n  description,\n  hint,\n  error,\n  required,\n  layout = 'stacked',\n  children,\n  className,\n  ...rest\n}: FieldProps) {\n  const generatedId = useId()\n  const controlId = htmlFor ?? generatedId\n  const message = error ?? hint\n  const messageId = message != null ? `${controlId}-${error != null ? 'error' : 'hint'}` : undefined\n  const descriptionId = description != null ? `${controlId}-description` : undefined\n  const labelId = label != null ? `${controlId}-label` : undefined\n\n  let control = children\n  if (isValidElement(children)) {\n    const child = children as WirableControl\n    control = cloneElement(child, {\n      id: child.props.id ?? controlId,\n      'aria-describedby':\n        [child.props['aria-describedby'], descriptionId, messageId].filter(Boolean).join(' ') ||\n        undefined,\n      'aria-required': required || child.props['aria-required'] || undefined,\n      'aria-invalid':\n        error != null ? (child.props['aria-invalid'] ?? true) : child.props['aria-invalid'],\n    })\n  } else if (DEV) {\n    warn({\n      code: 'FIELD_CONTROL_NOT_WIRED',\n      problem:\n        \"Field's child is not a single React element, so the label, aria-describedby, aria-required and aria-invalid were not applied to any control.\",\n      field: 'children',\n      fix: 'Put exactly one control element directly inside Field. For a row of controls, give each its own Field and lay them out around it.',\n      component: 'Field',\n    })\n  }\n\n  if (DEV && isValidElement(children) && typeof children.type === 'string') {\n    // A wrapper is the failure this exists for, and it is the one that looks\n    // most correct: `<Field><div><Input /></div></Field>` renders, and the\n    // label points at the DIV. The id, the describedby and the invalid state\n    // all land on a box, the control inside gets none of them, and a browser\n    // shows nothing wrong.\n    //\n    // Narrowed to HOST elements because that is the half that can be decided:\n    // a lowercase tag either takes a label or it does not. A function component\n    // might forward its props to a real control, and warning on those would\n    // fire on every correct use of Input, Select and the rest.\n    const LABELLABLE = ['input', 'select', 'textarea', 'button', 'meter', 'output', 'progress']\n    if (!LABELLABLE.includes(children.type)) {\n      warn({\n        code: 'FIELD_CONTROL_NOT_LABELLABLE',\n        problem: `Field's child is a <${children.type}>, which cannot take a label — so the id, aria-describedby, aria-required and aria-invalid were applied to it rather than to a control.`,\n        field: 'children',\n        fix: 'Put the control itself directly inside Field, with no wrapper. For a row of controls, give each its own Field and lay them out around it.',\n        component: 'Field',\n      })\n    }\n  }\n\n  // The label's id, for the controls that have to name themselves from it —\n  // everything else the field decided is already on the cloned child.\n  const wired = <FieldControlProvider value={{ labelId }}>{control}</FieldControlProvider>\n\n  const heading = (label != null || description != null) && (\n    <div className=\"flex flex-col gap-1\">\n      {label != null && (\n        <Label id={labelId} htmlFor={controlId} className=\"text-sm text-(--ink)\">\n          {label}\n          {required && (\n            <span className=\"text-(--danger)\" aria-hidden=\"true\">\n              {' '}\n              *\n            </span>\n          )}\n        </Label>\n      )}\n      {description != null && (\n        <p id={descriptionId} className=\"m-0 text-xs text-(--ink-3-aa)\">\n          {description}\n        </p>\n      )}\n    </div>\n  )\n\n  const note = message != null && (\n    <p\n      id={messageId}\n      className={cn('m-0 text-xs', error != null ? 'text-(--danger)' : 'text-(--ink-3-aa)')}\n    >\n      {message}\n    </p>\n  )\n\n  if (layout === 'row') {\n    return (\n      <div className={cn('flex flex-col gap-1.5', className)} {...rest}>\n        {/* `items-start` and not `items-center`: a description of two lines\n            would otherwise drag the switch down to the middle of the paragraph,\n            and a column of settings rows would have its controls on five\n            different lines. */}\n        <div className=\"flex items-start justify-between gap-6\">\n          <div className=\"min-w-0 flex-1\">{heading}</div>\n          <div className=\"shrink-0\">{wired}</div>\n        </div>\n        {note}\n      </div>\n    )\n  }\n\n  return (\n    <div className={cn('flex flex-col gap-1.5', className)} {...rest}>\n      {heading}\n      {wired}\n      {note}\n    </div>\n  )\n}\n\nexport default Field\n"],"mappings":";AA8LgB,cAQJ,YARI;AA5LhB,SAAS,aAAa;AACtB,SAAS,cAAc,gBAAgB,aAAa;AAEpD,SAAS,UAAU;AACnB,SAAS,KAAK,YAAY;AAC1B,SAAS,4BAA4B;AAoH9B,SAAS,MAAM;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,SAAS;AAAA,EACT;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAe;AACb,QAAM,cAAc,MAAM;AAC1B,QAAM,YAAY,WAAW;AAC7B,QAAM,UAAU,SAAS;AACzB,QAAM,YAAY,WAAW,OAAO,GAAG,SAAS,IAAI,SAAS,OAAO,UAAU,MAAM,KAAK;AACzF,QAAM,gBAAgB,eAAe,OAAO,GAAG,SAAS,iBAAiB;AACzE,QAAM,UAAU,SAAS,OAAO,GAAG,SAAS,WAAW;AAEvD,MAAI,UAAU;AACd,MAAI,eAAe,QAAQ,GAAG;AAC5B,UAAM,QAAQ;AACd,cAAU,aAAa,OAAO;AAAA,MAC5B,IAAI,MAAM,MAAM,MAAM;AAAA,MACtB,oBACE,CAAC,MAAM,MAAM,kBAAkB,GAAG,eAAe,SAAS,EAAE,OAAO,OAAO,EAAE,KAAK,GAAG,KACpF;AAAA,MACF,iBAAiB,YAAY,MAAM,MAAM,eAAe,KAAK;AAAA,MAC7D,gBACE,SAAS,OAAQ,MAAM,MAAM,cAAc,KAAK,OAAQ,MAAM,MAAM,cAAc;AAAA,IACtF,CAAC;AAAA,EACH,WAAW,KAAK;AACd,SAAK;AAAA,MACH,MAAM;AAAA,MACN,SACE;AAAA,MACF,OAAO;AAAA,MACP,KAAK;AAAA,MACL,WAAW;AAAA,IACb,CAAC;AAAA,EACH;AAEA,MAAI,OAAO,eAAe,QAAQ,KAAK,OAAO,SAAS,SAAS,UAAU;AAWxE,UAAM,aAAa,CAAC,SAAS,UAAU,YAAY,UAAU,SAAS,UAAU,UAAU;AAC1F,QAAI,CAAC,WAAW,SAAS,SAAS,IAAI,GAAG;AACvC,WAAK;AAAA,QACH,MAAM;AAAA,QACN,SAAS,uBAAuB,SAAS,IAAI;AAAA,QAC7C,OAAO;AAAA,QACP,KAAK;AAAA,QACL,WAAW;AAAA,MACb,CAAC;AAAA,IACH;AAAA,EACF;AAIA,QAAM,QAAQ,oBAAC,wBAAqB,OAAO,EAAE,QAAQ,GAAI,mBAAQ;AAEjE,QAAM,WAAW,SAAS,QAAQ,eAAe,SAC/C,qBAAC,SAAI,WAAU,uBACZ;AAAA,aAAS,QACR,qBAAC,SAAM,IAAI,SAAS,SAAS,WAAW,WAAU,wBAC/C;AAAA;AAAA,MACA,YACC,qBAAC,UAAK,WAAU,mBAAkB,eAAY,QAC3C;AAAA;AAAA,QAAI;AAAA,SAEP;AAAA,OAEJ;AAAA,IAED,eAAe,QACd,oBAAC,OAAE,IAAI,eAAe,WAAU,iCAC7B,uBACH;AAAA,KAEJ;AAGF,QAAM,OAAO,WAAW,QACtB;AAAA,IAAC;AAAA;AAAA,MACC,IAAI;AAAA,MACJ,WAAW,GAAG,eAAe,SAAS,OAAO,oBAAoB,mBAAmB;AAAA,MAEnF;AAAA;AAAA,EACH;AAGF,MAAI,WAAW,OAAO;AACpB,WACE,qBAAC,SAAI,WAAW,GAAG,yBAAyB,SAAS,GAAI,GAAG,MAK1D;AAAA,2BAAC,SAAI,WAAU,0CACb;AAAA,4BAAC,SAAI,WAAU,kBAAkB,mBAAQ;AAAA,QACzC,oBAAC,SAAI,WAAU,YAAY,iBAAM;AAAA,SACnC;AAAA,MACC;AAAA,OACH;AAAA,EAEJ;AAEA,SACE,qBAAC,SAAI,WAAW,GAAG,yBAAyB,SAAS,GAAI,GAAG,MACzD;AAAA;AAAA,IACA;AAAA,IACA;AAAA,KACH;AAEJ;AAEA,IAAO,gBAAQ;","names":[]}

package/dist/components/Field/field-control.d.ts

@@ -0,0 +1,31 @@
+import * as react from 'react';
+
+/**
+ * The one thing a `Field` cannot hand its control as a prop: where its label is.
+ *
+ * Everything else the field decides — the id, `aria-describedby`,
+ * `aria-required`, `aria-invalid` — travels as props on the cloned child, and a
+ * control that swallowed them was simply not forwarding them to the element
+ * that carries the role. That is a bug in the control, not a missing channel.
+ *
+ * A NAME is different. A trigger whose text is its value has to be named by the
+ * label AND by itself, which is two ids in one `aria-labelledby`; a group has to
+ * point BACK at the label, because `<label for>` does not bind to a
+ * `role="radiogroup"`. Neither can be expressed by a value the field computes on
+ * its own, so the label's id is published here and the control assembles the
+ * rest.
+ */
+interface FieldControl {
+    /** The label element's id, or undefined when the field has no label. */
+    labelId?: string;
+}
+declare const FieldControlProvider: react.Provider<FieldControl | null>;
+/**
+ * The enclosing `Field`'s label, if there is one.
+ *
+ * Null is a supported state, not a failure: every control here works outside a
+ * field, and each names itself from its own `label` prop when it must.
+ */
+declare function useFieldControl(): FieldControl | null;
+
+export { type FieldControl, FieldControlProvider, useFieldControl };

package/dist/components/Field/field-control.js

@@ -0,0 +1,12 @@
+"use client";
+import { createContext, useContext } from "react";
+const FieldControlContext = createContext(null);
+const FieldControlProvider = FieldControlContext.Provider;
+function useFieldControl() {
+  return useContext(FieldControlContext);
+}
+export {
+  FieldControlProvider,
+  useFieldControl
+};
+//# sourceMappingURL=field-control.js.map

package/dist/components/Field/field-control.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/Field/field-control.ts"],"sourcesContent":["'use client'\n\nimport { createContext, useContext } from 'react'\n\n/**\n * The one thing a `Field` cannot hand its control as a prop: where its label is.\n *\n * Everything else the field decides — the id, `aria-describedby`,\n * `aria-required`, `aria-invalid` — travels as props on the cloned child, and a\n * control that swallowed them was simply not forwarding them to the element\n * that carries the role. That is a bug in the control, not a missing channel.\n *\n * A NAME is different. A trigger whose text is its value has to be named by the\n * label AND by itself, which is two ids in one `aria-labelledby`; a group has to\n * point BACK at the label, because `<label for>` does not bind to a\n * `role=\"radiogroup\"`. Neither can be expressed by a value the field computes on\n * its own, so the label's id is published here and the control assembles the\n * rest.\n */\nexport interface FieldControl {\n  /** The label element's id, or undefined when the field has no label. */\n  labelId?: string\n}\n\nconst FieldControlContext = createContext<FieldControl | null>(null)\n\nexport const FieldControlProvider = FieldControlContext.Provider\n\n/**\n * The enclosing `Field`'s label, if there is one.\n *\n * Null is a supported state, not a failure: every control here works outside a\n * field, and each names itself from its own `label` prop when it must.\n */\nexport function useFieldControl(): FieldControl | null {\n  return useContext(FieldControlContext)\n}\n"],"mappings":";AAEA,SAAS,eAAe,kBAAkB;AAsB1C,MAAM,sBAAsB,cAAmC,IAAI;AAE5D,MAAM,uBAAuB,oBAAoB;AAQjD,SAAS,kBAAuC;AACrD,SAAO,WAAW,mBAAmB;AACvC;","names":[]}

package/dist/components/FloatingIconButton/FloatingIconButton.js

@@ -1,6 +1,7 @@
 "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,
@@ -9,6 +10,7 @@ function FloatingIconButton({
   className,
   ...rest
 }) {
+  warnBlankName("FloatingIconButton", "label", label, 'the button is announced as "button" and nothing else');
   return /* @__PURE__ */ jsx(
     "button",
     {

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/components/FloatingIconButton/FloatingIconButton.tsx"],"sourcesContent":["'use client'\n\nimport type { ButtonHTMLAttributes, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\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  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":";AAgDI;AA7CJ,SAAS,UAAU;AAuBnB,MAAM,iBAAiB,EAAE,OAAO,qBAAqB,KAAK,iBAAiB;AAcpE,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAA4B;AAC1B,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":[]}
+{"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-mono text-[11px] uppercase leading-[1.6] tracking-[0.2em] 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-mono text-[11px] uppercase leading-[1.6] tracking-[0.2em] 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/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