@hackcove/ui 0.2.2 → 0.2.4

package/dist/shownDate.d.ts

@@ -0,0 +1,45 @@
+import type { CalendarDate } from "@internationalized/date";
+import { type FocusEvent, type ReactElement } from "react";
+import type { DateFieldProps, Read } from "./DateField.js";
+type ValueKeys = "value" | "defaultValue" | "onChange" | "minValue" | "maxValue" | "isRequired";
+/** The value props, each of which may be passed as `undefined`. */
+type ValueProps = {
+    [K in ValueKeys]?: DateFieldProps[K] | undefined;
+};
+/**
+ * The value the field reports is always what it shows: the typed date when it is complete, exists
+ * and is within min/max, else `null`. Two parts of React Aria disagree with that, so this owns both:
+ *
+ * - **The value.** React Aria keeps its last valid date behind an impossible or partly cleared
+ *   display, and reports an out-of-range one. So the consumer's `onChange` is fired from what the
+ *   segments read, once per change: a valid date turning invalid reports `null`. React Aria itself
+ *   is controlled by `inner`, so a parent holding that `null` does not wipe the typed segments; a
+ *   `value` the parent sets that differs from the last report is passed through, and not reported
+ *   back. Because React Aria's own value goes stale, `validate` checks `isRequired` against the
+ *   segments: a partly filled required field blocks the form.
+ * - **Keeping an impossible date.** When focus leaves a complete field, React Aria moves an
+ *   impossible day to the month's last and reports that date (`confirmPlaceholder`); it skips this
+ *   for a read-only field. So while the typed date is impossible, the field is read-only for exactly
+ *   the blur that leaves it: `onBlurCapture` on a wrapper of the input turns it on before React
+ *   Aria's blur handler runs, and the field's own `onBlur`, which runs after it, turns it off again.
+ *
+ * `shown` (`YYYY-MM-DD` or `""`) is what the hidden `name` input posts.
+ */
+export declare function useShownDate(props: ValueProps): {
+    inner: CalendarDate | null;
+    setInner: import("react").Dispatch<import("react").SetStateAction<CalendarDate | null>>;
+    shown: string;
+    impossible: string | null;
+    onRead: (next: Read) => void;
+    validate: () => "Enter the whole date." | null;
+    leaving: boolean;
+    onBlurCapture: (event: FocusEvent<HTMLElement>) => void;
+    onLeft: () => void;
+};
+/** The hidden input a form posts under `name`: the shown date as `YYYY-MM-DD`, or `""`. */
+export declare function ShownInput({ name, shown, isDisabled, }: {
+    name: string | undefined;
+    shown: string;
+    isDisabled: boolean | undefined;
+}): ReactElement | null;
+export {};

package/dist/shownDate.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState, } from "react";
+import { flushSync } from "react-dom";
+import { fromISODate, toISODate } from "./isoDate.js";
+/** `iso` when it is a date within min/max, else `""`. */
+function withinRange(iso, { minValue, maxValue }) {
+    const date = fromISODate(iso);
+    if (!date)
+        return "";
+    if (minValue && date.compare(minValue) < 0)
+        return "";
+    if (maxValue && date.compare(maxValue) > 0)
+        return "";
+    return iso;
+}
+/**
+ * The value the field reports is always what it shows: the typed date when it is complete, exists
+ * and is within min/max, else `null`. Two parts of React Aria disagree with that, so this owns both:
+ *
+ * - **The value.** React Aria keeps its last valid date behind an impossible or partly cleared
+ *   display, and reports an out-of-range one. So the consumer's `onChange` is fired from what the
+ *   segments read, once per change: a valid date turning invalid reports `null`. React Aria itself
+ *   is controlled by `inner`, so a parent holding that `null` does not wipe the typed segments; a
+ *   `value` the parent sets that differs from the last report is passed through, and not reported
+ *   back. Because React Aria's own value goes stale, `validate` checks `isRequired` against the
+ *   segments: a partly filled required field blocks the form.
+ * - **Keeping an impossible date.** When focus leaves a complete field, React Aria moves an
+ *   impossible day to the month's last and reports that date (`confirmPlaceholder`); it skips this
+ *   for a read-only field. So while the typed date is impossible, the field is read-only for exactly
+ *   the blur that leaves it: `onBlurCapture` on a wrapper of the input turns it on before React
+ *   Aria's blur handler runs, and the field's own `onBlur`, which runs after it, turns it off again.
+ *
+ * `shown` (`YYYY-MM-DD` or `""`) is what the hidden `name` input posts.
+ */
+export function useShownDate(props) {
+    const { value, defaultValue, onChange, isRequired } = props;
+    const [inner, setInner] = useState(value ?? defaultValue ?? null);
+    const [read, setRead] = useState({
+        typed: toISODate(inner),
+        impossible: null,
+        partial: false,
+    });
+    const [leaving, setLeaving] = useState(false);
+    const shown = withinRange(read.typed, props);
+    const reported = useRef(shown);
+    const report = useRef(onChange);
+    useEffect(() => {
+        report.current = onChange;
+    });
+    const given = value === undefined ? undefined : toISODate(value);
+    const givenShown = withinRange(given ?? "", props);
+    const lastGiven = useRef(given);
+    useEffect(() => {
+        if (given === lastGiven.current)
+            return;
+        lastGiven.current = given;
+        if (given === undefined || given === reported.current)
+            return;
+        reported.current = givenShown;
+        setInner(fromISODate(given));
+    }, [given, givenShown]);
+    const onRead = useCallback((next) => setRead(next), []);
+    useEffect(() => {
+        if (shown === reported.current)
+            return;
+        reported.current = shown;
+        report.current?.(fromISODate(shown));
+    }, [shown]);
+    return {
+        inner,
+        setInner,
+        shown,
+        impossible: read.impossible,
+        onRead,
+        validate: () => (isRequired && read.partial ? "Enter the whole date." : null),
+        leaving,
+        onBlurCapture: (event) => {
+            if (read.impossible && !event.currentTarget.contains(event.relatedTarget)) {
+                flushSync(() => setLeaving(true));
+            }
+        },
+        onLeft: () => setLeaving(false),
+    };
+}
+/** The hidden input a form posts under `name`: the shown date as `YYYY-MM-DD`, or `""`. */
+export function ShownInput({ name, shown, isDisabled, }) {
+    return name ? _jsx("input", { type: "hidden", name: name, value: shown, disabled: isDisabled }) : null;
+}

package/dist/typography.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ElementType, ReactElement, ReactNode } from "react";
 export type TypographyColor = "default" | "secondary" | "tertiary" | "muted" | "brand";
 /** Own props shared by every typography component; the rest follow the rendered element. */
 type OwnProps = {
@@ -19,57 +19,65 @@ export type TypographyProps<E extends ElementType> = OwnProps & {
  * overriding PageHeading's size.
  */
 export declare const Display: {
-    <E extends ElementType = "h1">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "h1">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 /** The supporting sentence under a `Display`. `p`, text-lg/7 normal, secondary. */
 export declare const Lead: {
-    <E extends ElementType = "p">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "p">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 /** Page title. `h1`, text-2xl/8 semibold, primary text. */
 export declare const PageHeading: {
-    <E extends ElementType = "h1">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
-    displayName: string;
-};
-/** Top-level section header. `h2`, text-base/6 semibold, primary text. */
-export declare const SectionHeading: {
-    <E extends ElementType = "h2">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
-    displayName: string;
-};
-/** Nested header. `h3`, text-sm/5 semibold, primary text. */
-export declare const SubsectionHeading: {
-    <E extends ElementType = "h3">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "h1">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
+/**
+ * Top-level section header. `h2`, text-base/6 semibold, primary text. `rule` sets
+ * a hairline under it (the `Divider` line colour) with the space either side of
+ * the line built in.
+ */
+export declare function SectionHeading<E extends ElementType = "h2">({ rule, ...props }: TypographyProps<E> & {
+    rule?: boolean;
+}): ReactElement;
+export type SubsectionHeadingSize = "sm" | "base" | "lg";
+/**
+ * Nested header. `h3`, text-sm/5 semibold, primary text. `size` steps it up for
+ * a card, drawer or form-group title: `sm` (default), `base` (bold) or `lg`.
+ */
+export declare function SubsectionHeading<E extends ElementType = "h3">({ size, ...props }: TypographyProps<E> & {
+    size?: SubsectionHeadingSize;
+}): ReactElement;
 /** Dialog/modal title. `h2`, text-base/6 semibold, primary text. */
 export declare const ModalHeading: {
-    <E extends ElementType = "h2">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "h2">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 /** Supporting line under a heading. `p`, text-sm/5 normal, secondary. */
 export declare const Subtitle: {
-    <E extends ElementType = "p">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "p">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 /** Small all-caps label above a group. `span`, text-xs semibold uppercase, tertiary. */
 export declare const Overline: {
-    <E extends ElementType = "span">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
-    displayName: string;
-};
-/** Default running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary. */
-export declare const Body: {
-    <E extends ElementType = "span">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "span">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
+/**
+ * Default running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary.
+ * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.
+ */
+export declare function Body<E extends ElementType = "span">({ preserveNewlines, ...props }: TypographyProps<E> & {
+    preserveNewlines?: boolean;
+}): ReactElement;
 /** Emphasised run of body text. `span`, text-sm/5 medium, primary text. */
 export declare const BodyStrong: {
-    <E extends ElementType = "span">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "span">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 /** Fine print / metadata. `span` (inline; `as="p"` for a block), text-xs/4 normal, tertiary. */
 export declare const Caption: {
-    <E extends ElementType = "span">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    <E extends ElementType = "span">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
 export {};

package/dist/typography.js

@@ -15,13 +15,20 @@ const COLOR = {
  * layout classes — never the pinned size/weight.
  */
 function typography(displayName, defaultAs, variantClass, defaultColor) {
-    function Typography({ as, color, className, children, ...rest }) {
-        const Tag = as ?? defaultAs;
-        return (_jsx(Tag, { className: cx(variantClass, COLOR[color ?? defaultColor], className), ...rest, children: children }));
+    function Typography(props) {
+        return pinned(defaultAs, variantClass, defaultColor, props);
     }
     Typography.displayName = displayName;
     return Typography;
 }
+/**
+ * The one place a pinned role renders. The few roles with an opt-in prop of their own are
+ * written by hand, not by `typography`, and call this too.
+ */
+function pinned(defaultAs, variantClass, defaultColor, { as, color, className, children, ...rest }) {
+    const Tag = as ?? defaultAs;
+    return (_jsx(Tag, { className: cx(variantClass, COLOR[color ?? defaultColor], className), ...rest, children: children }));
+}
 // --- Structural roles (block by default) -----------------------------------
 /**
  * Marketing-scale headline — the one line at the top of a public page. `h1`,
@@ -35,10 +42,27 @@ export const Display = typography("Display", "h1", "text-4xl/[1.1] font-semibold
 export const Lead = typography("Lead", "p", "text-lg/7 font-normal sm:text-xl/8", "secondary");
 /** Page title. `h1`, text-2xl/8 semibold, primary text. */
 export const PageHeading = typography("PageHeading", "h1", "text-2xl/8 font-semibold tracking-tight", "default");
-/** Top-level section header. `h2`, text-base/6 semibold, primary text. */
-export const SectionHeading = typography("SectionHeading", "h2", "text-base/6 font-semibold", "default");
-/** Nested header. `h3`, text-sm/5 semibold, primary text. */
-export const SubsectionHeading = typography("SubsectionHeading", "h3", "text-sm/5 font-semibold", "default");
+/**
+ * Top-level section header. `h2`, text-base/6 semibold, primary text. `rule` sets
+ * a hairline under it (the `Divider` line colour) with the space either side of
+ * the line built in.
+ */
+export function SectionHeading({ rule, ...props }) {
+    const variant = cx(rule && "mb-4 border-b border-slate-200/70 pb-2", "text-base/6 font-semibold");
+    return pinned("h2", variant, "default", props);
+}
+const SUBSECTION_SIZE = {
+    sm: "text-sm/5 font-semibold",
+    base: "text-base/6 font-bold",
+    lg: "text-lg/7 font-semibold",
+};
+/**
+ * Nested header. `h3`, text-sm/5 semibold, primary text. `size` steps it up for
+ * a card, drawer or form-group title: `sm` (default), `base` (bold) or `lg`.
+ */
+export function SubsectionHeading({ size = "sm", ...props }) {
+    return pinned("h3", SUBSECTION_SIZE[size], "default", props);
+}
 /** Dialog/modal title. `h2`, text-base/6 semibold, primary text. */
 export const ModalHeading = typography("ModalHeading", "h2", "text-base/6 font-semibold", "default");
 /** Supporting line under a heading. `p`, text-sm/5 normal, secondary. */
@@ -46,8 +70,14 @@ export const Subtitle = typography("Subtitle", "p", "text-sm/5 font-normal", "se
 // --- Inline roles (inline by default) --------------------------------------
 /** Small all-caps label above a group. `span`, text-xs semibold uppercase, tertiary. */
 export const Overline = typography("Overline", "span", "text-xs font-semibold uppercase tracking-wide", "tertiary");
-/** Default running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary. */
-export const Body = typography("Body", "span", "text-sm/5 font-normal", "secondary");
+/**
+ * Default running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary.
+ * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.
+ */
+export function Body({ preserveNewlines, ...props }) {
+    const variant = cx(preserveNewlines && "whitespace-pre-line", "text-sm/5 font-normal");
+    return pinned("span", variant, "secondary", props);
+}
 /** Emphasised run of body text. `span`, text-sm/5 medium, primary text. */
 export const BodyStrong = typography("BodyStrong", "span", "text-sm/5 font-medium", "default");
 /** Fine print / metadata. `span` (inline; `as="p"` for a block), text-xs/4 normal, tertiary. */

package/dist/ui.d.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+/** @deprecated use PageHeader */
 export declare function PageTitle({ title, subtitle }: {
     title: string;
     subtitle?: string;

package/dist/ui.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "./cx.js";
+import { PageHeaderContent } from "./PageHeader.js";
 // Small presentational primitives written against Tailwind's slate-based class vocabulary
 // (remapped to Catppuccin Mocha in dark mode by theme.css).
+/** @deprecated use PageHeader */
 export function PageTitle({ title, subtitle }) {
-    return (_jsxs("div", { children: [_jsx("h1", { className: "text-2xl font-bold tracking-tight text-slate-900", children: title }), subtitle && _jsx("p", { className: "mt-1 text-sm text-slate-500", children: subtitle })] }));
+    return _jsx(PageHeaderContent, { title: title, subtitle: subtitle });
 }
 /** A bordered panel with an optional title and count; `as` picks the element (default `section`). */
 export function Card({ title, count, as: Tag = "section", className, children, }) {

package/package.json

@@ -1,8 +1,26 @@
 {
   "name": "@hackcove/ui",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Hack Cove React components: primitives, typography roles and a safe Markdown renderer, written against Tailwind v4 utilities. Pair with a @hackcove/theme-* package.",
+  "keywords": [
+    "components",
+    "design-system",
+    "hackcove",
+    "markdown",
+    "react",
+    "tailwind",
+    "tailwindcss",
+    "ui"
+  ],
+  "homepage": "https://github.com/madangryscientist/hackcove/tree/main/packages/ui#readme",
+  "bugs": {
+    "url": "https://github.com/madangryscientist/hackcove/issues"
+  },
   "license": "MIT",
+  "author": {
+    "name": "Jacobus Langner",
+    "url": "https://github.com/madangryscientist"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/madangryscientist/hackcove.git",
@@ -29,6 +47,10 @@
     "pack-check": "npm pack --dry-run",
     "prepack": "bun run build"
   },
+  "dependencies": {
+    "@internationalized/date": "^3.12.4",
+    "react-aria-components": "^1.22.1"
+  },
   "devDependencies": {
     "@types/bun": "1.4.3",
     "@types/react": "^19.3.0",
@@ -41,6 +63,7 @@
   },
   "peerDependencies": {
     "react": ">=18",
+    "react-dom": ">=18",
     "tailwindcss": "^4"
   },
   "nx": {