@hackcove/ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacobus Langner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @hackcove/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hack Cove React components, written against Tailwind v4 utilities. They carry no theme: pair them
+with a `@hackcove/theme-*` package such as `@hackcove/theme-catppuccin-mocha`, or use them on their
+own for the default light look.
+
+Status: `0.x`, not yet published to npm. License: MIT.
+
+## Install
+
+```sh
+bun add @hackcove/ui
+# peers: react >= 18, tailwindcss ^4
+```
+
+Tailwind skips `node_modules`, so tell it to scan the build for the utilities the components use,
+in the stylesheet that imports Tailwind (the path is relative to that file):
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@hackcove/ui/dist";
+```
+
+## Use
+
+```tsx
+import { Body, Card, PageHeading, Pill } from "@hackcove/ui";
+
+export const Example = () => (
+  <Card title="Status" count={2}>
+    <PageHeading>All good</PageHeading>
+    <Body>Two things shipped.</Body> <Pill tone="emerald">ok</Pill>
+  </Card>
+);
+```
+
+## What is exported
+
+- Primitives: `Card`, `EpicHeader`, `Empty`, `PageTitle`, `Pill`, `groupByEpic`, `Markdown`.
+- Typography roles (each pins size + weight, takes a `color` and an `as`): `Display`, `Lead`,
+  `PageHeading`, `SectionHeading`, `SubsectionHeading`, `ModalHeading`, `Subtitle`, `Overline`,
+  `Body`, `BodyStrong`, `Caption`.
+
+## Develop
+
+From the workspace root: `bunx nx run-many -t typecheck lint test build -p ui` and
+`bunx nx pack-check ui` (the tarball is `dist/` plus `package.json`, `README.md`, `LICENSE`).
+The stories live in `apps/storybook`.

package/dist/Markdown.d.ts

@@ -0,0 +1,3 @@
+export declare function Markdown({ md }: {
+    md: string;
+}): import("react").JSX.Element;

package/dist/Markdown.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// A minimal, SAFE markdown renderer for the standup (headings / bullets / bold). No
+// dangerouslySetInnerHTML — text is rendered as React nodes, so it can't inject HTML.
+function inline(text) {
+    return text.split(/(\*\*[^*]+\*\*)/g).map((p, i) => p.startsWith("**") && p.endsWith("**") ? (_jsx("strong", { className: "font-semibold text-slate-900", children: p.slice(2, -2) }, i)) : (_jsx("span", { children: p }, i)));
+}
+export function Markdown({ md }) {
+    const out = [];
+    let bullets = [];
+    const flush = () => {
+        if (bullets.length) {
+            out.push(_jsx("ul", { className: "ml-4 list-disc space-y-1", children: bullets }, `u${out.length}`));
+            bullets = [];
+        }
+    };
+    md.split("\n").forEach((ln, i) => {
+        const t = ln.trim();
+        if (t.startsWith("## ")) {
+            flush();
+            out.push(_jsx("h2", { className: "mt-4 text-xs font-semibold uppercase tracking-wide text-slate-400 first:mt-0", children: t.slice(3) }, i));
+        }
+        else if (t.startsWith("### ")) {
+            flush();
+            out.push(_jsx("h3", { className: "mt-3 text-sm font-semibold text-slate-700", children: t.slice(4) }, i));
+        }
+        else if (t.startsWith("- ") || t.startsWith("* ")) {
+            bullets.push(_jsx("li", { className: "text-sm text-slate-700", children: inline(t.slice(2)) }, i));
+        }
+        else if (t === "") {
+            flush();
+        }
+        else {
+            flush();
+            out.push(_jsx("p", { className: "text-sm text-slate-700", children: inline(t) }, i));
+        }
+    });
+    flush();
+    return _jsx("div", { className: "space-y-1", children: out });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Card, EpicHeader, Empty, PageTitle, Pill, groupByEpic } from "./ui.js";
+export { Markdown } from "./Markdown.js";
+export { Body, BodyStrong, Caption, Display, Lead, ModalHeading, Overline, PageHeading, SectionHeading, SubsectionHeading, Subtitle, type TypographyColor, type TypographyProps, } from "./typography.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Card, EpicHeader, Empty, PageTitle, Pill, groupByEpic } from "./ui.js";
+export { Markdown } from "./Markdown.js";
+export { Body, BodyStrong, Caption, Display, Lead, ModalHeading, Overline, PageHeading, SectionHeading, SubsectionHeading, Subtitle, } from "./typography.js";

package/dist/typography.d.ts

@@ -0,0 +1,75 @@
+import type { ComponentPropsWithoutRef, ElementType, 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 = {
+    /** Colour token; each component sets a sensible default. */
+    color?: TypographyColor;
+    className?: string;
+    children?: ReactNode;
+};
+/** Polymorphic props: own props + `as` + the intrinsic props of whichever element `as` selects. */
+export type TypographyProps<E extends ElementType> = OwnProps & {
+    as?: E;
+} & Omit<ComponentPropsWithoutRef<E>, keyof OwnProps | "as">;
+/**
+ * Marketing-scale headline — the one line at the top of a public page. `h1`,
+ * text-4xl/tight semibold, primary text, growing to text-6xl on wider screens.
+ * `PageHeading`'s scale is deliberately dev-tool sized; a brochure
+ * hero needs a display scale, so it gets its own pinned role rather than callers
+ * overriding PageHeading's size.
+ */
+export declare const Display: {
+    <E extends ElementType = "h1">({ as, color, className, children, ...rest }: TypographyProps<E>): import("react").JSX.Element;
+    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;
+    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;
+    displayName: string;
+};
+/** 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;
+    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;
+    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;
+    displayName: string;
+};
+/** 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;
+    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;
+    displayName: string;
+};
+export {};

package/dist/typography.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/** Colour token → slate/violet utility (remapped to Catppuccin Mocha in dark mode by theme.css). */
+const COLOR = {
+    default: "text-slate-900", // Catppuccin text     #cdd6f4
+    secondary: "text-slate-600", // Catppuccin subtext1 #bac2de
+    tertiary: "text-slate-500", // Catppuccin subtext0 #a6adc8
+    muted: "text-slate-400", // Catppuccin overlay2 #9399b2
+    brand: "text-violet-600", // Catppuccin mauve    #cba6f7
+};
+function cx(...parts) {
+    return parts.filter(Boolean).join(" ");
+}
+/**
+ * Build a semantic component that pins `variantClass` (size + weight + tracking)
+ * and a default colour. The scale/weight for each role therefore lives in exactly
+ * one place (the call below), and callers can only vary the colour, element, and
+ * 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 }));
+    }
+    Typography.displayName = displayName;
+    return Typography;
+}
+// --- Structural roles (block by default) -----------------------------------
+/**
+ * Marketing-scale headline — the one line at the top of a public page. `h1`,
+ * text-4xl/tight semibold, primary text, growing to text-6xl on wider screens.
+ * `PageHeading`'s scale is deliberately dev-tool sized; a brochure
+ * hero needs a display scale, so it gets its own pinned role rather than callers
+ * overriding PageHeading's size.
+ */
+export const Display = typography("Display", "h1", "text-4xl/[1.1] font-semibold tracking-tight sm:text-5xl/[1.05] lg:text-6xl/[1.05]", "default");
+/** The supporting sentence under a `Display`. `p`, text-lg/7 normal, secondary. */
+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");
+/** 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. */
+export const Subtitle = typography("Subtitle", "p", "text-sm/5 font-normal", "secondary");
+// --- 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");
+/** 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. */
+export const Caption = typography("Caption", "span", "text-xs/4 font-normal", "tertiary");

package/dist/ui.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+export declare function PageTitle({ title, subtitle }: {
+    title: string;
+    subtitle?: string;
+}): import("react").JSX.Element;
+export declare function Card({ title, count, children, }: {
+    title?: string;
+    count?: number;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** A coloured epic header row: a dot in the epic's colour + its label. */
+export declare function EpicHeader({ color, label }: {
+    color: string;
+    label: string;
+}): import("react").JSX.Element;
+export declare function Pill({ children, tone, }: {
+    children: ReactNode;
+    tone?: "slate" | "amber" | "emerald" | "blue" | "red";
+}): import("react").JSX.Element;
+export declare function Empty({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Group items by their epic ref, ordered with real epics first (by ref) and "No epic" last. */
+export declare function groupByEpic<T>(items: T[], epicOf: (t: T) => string | null): [string | null, T[]][];

package/dist/ui.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Small presentational primitives written against Tailwind's slate-based class vocabulary
+// (remapped to Catppuccin Mocha in dark mode by theme.css).
+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 })] }));
+}
+export function Card({ title, count, children, }) {
+    return (_jsxs("section", { className: "rounded-xl border border-slate-200/70 bg-white p-5 shadow-sm", children: [title && (_jsxs("div", { className: "mb-3 flex items-baseline gap-2", children: [_jsx("h2", { className: "text-xs font-semibold uppercase tracking-wide text-slate-400", children: title }), count !== undefined && (_jsx("span", { className: "text-xs font-medium text-slate-400", children: count }))] })), children] }));
+}
+/** A coloured epic header row: a dot in the epic's colour + its label. */
+export function EpicHeader({ color, label }) {
+    return (_jsxs("div", { className: "mb-1.5 mt-3 flex items-center gap-2 first:mt-0", children: [_jsx("span", { className: "inline-block h-2.5 w-2.5 rounded-full", style: { backgroundColor: color } }), _jsx("span", { className: "text-sm font-semibold text-slate-700", children: label })] }));
+}
+export function Pill({ children, tone = "slate", }) {
+    const tones = {
+        slate: "bg-slate-100 text-slate-600",
+        amber: "bg-amber-50 text-amber-700",
+        emerald: "bg-emerald-50 text-emerald-700",
+        blue: "bg-blue-50 text-blue-700",
+        red: "bg-red-50 text-red-900",
+    };
+    return (_jsx("span", { className: `rounded-md px-1.5 py-0.5 text-xs font-medium ${tones[tone]}`, children: children }));
+}
+export function Empty({ children }) {
+    return _jsx("p", { className: "text-sm text-slate-400", children: children });
+}
+function compareEpics(a, b) {
+    if (a === null)
+        return 1;
+    if (b === null)
+        return -1;
+    return a < b ? -1 : 1;
+}
+/** Group items by their epic ref, ordered with real epics first (by ref) and "No epic" last. */
+export function groupByEpic(items, epicOf) {
+    const groups = new Map();
+    for (const item of items) {
+        const key = epicOf(item) ?? null;
+        const group = groups.get(key);
+        if (group)
+            group.push(item);
+        else
+            groups.set(key, [item]);
+    }
+    return [...groups].toSorted(([a], [b]) => compareEpics(a, b));
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@hackcove/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Hack Cove React components: primitives, typography roles and a safe Markdown renderer, written against Tailwind v4 utilities. Pair with a @hackcove/theme-* package.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/madangryscientist/hackcove.git",
+    "directory": "packages/ui"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint -c ../../.oxlintrc.json --type-aware --deny-warnings && bun ../../scripts/check-slop.ts",
+    "test": "vitest run",
+    "pack-check": "npm pack --dry-run",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "tailwindcss": "^4.3.3",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "tailwindcss": "^4"
+  },
+  "nx": {
+    "name": "ui",
+    "tags": [
+      "kind:package"
+    ],
+    "targets": {
+      "build": {
+        "outputs": [
+          "{projectRoot}/dist"
+        ]
+      }
+    }
+  }
+}