@jdcpuwiz/homelab-ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,302 @@
+import * as react from 'react';
+import { ClassValue } from 'clsx';
+
+type Variant = "primary" | "secondary" | "tertiary" | "danger";
+type Size = "sm" | "md";
+type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    variant?: Variant;
+    size?: Size;
+};
+/**
+ * Homelab Button. Use the variant + size props; never pass raw color
+ * classes through className. className is for layout extras only
+ * (e.g. `w-full`).
+ */
+declare const Button: react.ForwardRefExoticComponent<react.ButtonHTMLAttributes<HTMLButtonElement> & {
+    variant?: Variant;
+    size?: Size;
+} & react.RefAttributes<HTMLButtonElement>>;
+
+type ConfirmDialogProps = {
+    open: boolean;
+    title: string;
+    message: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    tone?: "danger" | "primary";
+    onConfirm: () => void;
+    onClose: () => void;
+};
+/**
+ * Confirm/cancel dialog built on Modal + Button. Enter triggers confirm,
+ * Esc cancels (via Modal's built-in handling).
+ */
+declare function ConfirmDialog({ open, title, message, confirmLabel, cancelLabel, tone, onConfirm, onClose, }: ConfirmDialogProps): react.JSX.Element;
+
+type EmptyStateProps = {
+    icon?: React.ReactNode;
+    title?: string;
+    message: string;
+    action?: React.ReactNode;
+    /**
+     * `panel` — large empty state with warm card background (page bodies).
+     * `inline` — compact text-only line for sidebar tree, popovers, etc.
+     */
+    variant?: "panel" | "inline";
+    className?: string;
+};
+declare function EmptyState({ icon, title, message, action, variant, className, }: EmptyStateProps): react.JSX.Element;
+
+type Density = "form" | "media";
+type ModalProps = {
+    open: boolean;
+    onClose: () => void;
+    title?: string;
+    /** Show the close X in the top right. Default: true when title is set. */
+    showClose?: boolean;
+    /**
+     * Overlay weight:
+     *   `form`  — dialogs / pickers / confirms (`bg-black/70`)
+     *   `media` — lightbox / asset preview (`bg-black/90`)
+     * Defaults to `form`.
+     */
+    density?: Density;
+    /** Max width — default `max-w-md`. */
+    maxWidth?: string;
+    /** Footer slot — render buttons here. Always right-aligned. */
+    footer?: React.ReactNode;
+    children: React.ReactNode;
+};
+/**
+ * Single modal frame. Every dialog routes through this:
+ *   - overlay + click-outside dismiss
+ *   - Esc-to-close
+ *   - role=dialog + aria-modal + aria-labelledby wiring
+ *   - DESIGN.md header treatment (uppercase tracking-widest)
+ *   - shared right-aligned footer row
+ */
+declare function Modal({ open, onClose, title, showClose, density, maxWidth, footer, children, }: ModalProps): react.JSX.Element | null;
+
+type Crumb = {
+    label: string;
+    onClick?: () => void;
+};
+type PageHeaderProps = {
+    title: string;
+    description?: string;
+    /** Back link rendered above the title. */
+    back?: {
+        href: string;
+        label: string;
+        render?: (href: string, children: React.ReactNode) => React.ReactNode;
+    };
+    /** Right-aligned actions slot. */
+    actions?: React.ReactNode;
+    /**
+     * Header image URL (e.g. `/logos.png`). When the URL resolves, the
+     * image is the visual title. When it 404s, a styled placeholder at
+     * the same dimensions takes its place — the layout stays stable so
+     * creating a new themed page "just works" the moment you drop a
+     * matching PNG in /public/.
+     *
+     * When `imageSrc` is undefined, no image block renders and the
+     * purple text-title becomes the visual title.
+     */
+    imageSrc?: string;
+    imageAlt?: string;
+    /**
+     * Breadcrumb trail. When provided, replaces the text title. Last
+     * crumb is current (white + bold); earlier crumbs are clickable.
+     */
+    breadcrumb?: Crumb[];
+    className?: string;
+};
+/**
+ * Page-header block. The image block reserves space whenever `imageSrc`
+ * is set — drop the PNG in /public/ and the layout just fills in.
+ *
+ * Text title rules:
+ *   - imageSrc set + image present → text becomes sr-only
+ *   - imageSrc set + image 404 → placeholder block + text becomes sr-only
+ *   - imageSrc unset → text title is visible
+ *   - breadcrumb provided → breadcrumb replaces text title regardless of image
+ *
+ * The back link uses a plain <a> by default. In Next.js, pass
+ * `back.render` to use next/link:
+ *
+ *   import Link from "next/link";
+ *   <PageHeader back={{ href: "/foo", label: "Back", render: (href, c) => <Link href={href}>{c}</Link> }} />
+ */
+declare function PageHeader({ title, description, back, actions, imageSrc, imageAlt, breadcrumb, className, }: PageHeaderProps): react.JSX.Element;
+
+type SidebarProps = {
+    /**
+     * Logo image src — typically `/logo.png` or `/<project>-logo-256.png`.
+     * Rendered at w-36 h-36 inside a centered block with px-4 pt-6 pb-5
+     * + border-b-2 (doghouse-canonical spec).
+     */
+    logoSrc: string;
+    /** Alt text for the logo + label shown in the mobile top bar. */
+    logoAlt: string;
+    /**
+     * Slots — every section is optional. Render them in this order:
+     *   1. Logo block (always)
+     *   2. widgets       — clock / weather / homepage rotator / etc
+     *   3. nav           — primary navigation
+     *   4. middle        — long-running content (folder tree, etc) — flex-1
+     *   5. lower         — secondary nav (manage-tags, settings link, etc)
+     *   6. (spacer)
+     *   7. admin         — admin section
+     *   8. footer        — version stamp, etc
+     */
+    widgets?: React.ReactNode;
+    nav?: React.ReactNode;
+    middle?: React.ReactNode;
+    lower?: React.ReactNode;
+    admin?: React.ReactNode;
+    footer?: React.ReactNode;
+    /**
+     * Mobile-drawer behavior. Controlled — the consumer owns the open
+     * state so they can wire it from anywhere (top-bar hamburger,
+     * keyboard shortcut, route change, etc.).
+     *
+     * When omitted, the Sidebar manages its own drawer state using the
+     * built-in mobile top bar (hamburger renders top-left on screens < md).
+     */
+    mobileOpen?: boolean;
+    onMobileOpenChange?: (open: boolean) => void;
+    /** Extra classes on the outer <aside>. */
+    className?: string;
+    /**
+     * When true, render a built-in mobile top bar (logo + hamburger) on
+     * screens < md. Defaults to true. Disable when the consumer renders
+     * its own top chrome.
+     */
+    showMobileTopBar?: boolean;
+};
+/**
+ * Canonical homelab sidebar shell. Doghouse is the reference impl;
+ * this is the extracted version every other project consumes.
+ *
+ * Dimensions are non-negotiable:
+ *   - md+ width: 15rem (`w-60` / `w-sidebar`)
+ *   - md+ position: fixed-flex in a `display:flex` parent
+ *   - mobile: off-canvas drawer at full sidebar width
+ *   - logo block: w-36 h-36 centered, px-4 pt-6 pb-5, border-b-2
+ *
+ * The component renders raw hex values (#111111, #1e1e1e) so it works
+ * even when the consumer skips the Tailwind preset. Apply the preset
+ * + globals.css for token-based overrides.
+ */
+declare function Sidebar({ logoSrc, logoAlt, widgets, nav, middle, lower, admin, footer, mobileOpen: controlledOpen, onMobileOpenChange, className, showMobileTopBar, }: SidebarProps): react.JSX.Element;
+
+type SidebarNavItemProps = {
+    label: string;
+    icon?: React.ReactNode;
+    active?: boolean;
+    onClick?: () => void;
+    /**
+     * When set, renders as <a href>. Otherwise renders as <button>. In
+     * Next.js, prefer passing `render` so you can wrap in next/link
+     * without losing classes:
+     *
+     *   <SidebarNavItem
+     *     label="Home"
+     *     href="/"
+     *     render={(props, children) => <Link {...props}>{children}</Link>}
+     *   />
+     */
+    href?: string;
+    render?: (props: {
+        href: string;
+        className: string;
+    }, children: React.ReactNode) => React.ReactNode;
+};
+/**
+ * Single nav row for the Sidebar's `nav` / `lower` slots. Matches the
+ * doghouse-canonical style: active = orange bg + white text, inactive =
+ * white/45 text + white/5 hover bg.
+ */
+declare function SidebarNavItem({ label, icon, active, onClick, href, render, }: SidebarNavItemProps): react.JSX.Element;
+
+type SpinnerProps = {
+    label?: string;
+    className?: string;
+};
+/**
+ * Consistent inline loading affordance — used wherever the app would
+ * otherwise say "Loading…" in plain text. Compact spinner + label, color
+ * is the same tertiary-text grey across the app.
+ */
+declare function Spinner({ label, className }: SpinnerProps): react.JSX.Element;
+
+type TagRef = {
+    id: string | number;
+    name: string;
+    color: string;
+};
+type TagChipsProps = {
+    tags: TagRef[];
+    size?: "xs" | "sm";
+    onClick?: (tag: TagRef) => void;
+};
+/**
+ * Render a row of solid-color tag chips. Yellow auto-flips text to
+ * black per the homelab status-palette contrast rule (see tagTextColor).
+ *
+ * Renders `<button>` when interactive (`onClick` set), `<span>` when
+ * read-only — keeps screen-reader semantics honest.
+ */
+declare function TagChips({ tags, size, onClick }: TagChipsProps): react.JSX.Element | null;
+
+/**
+ * Conditional Tailwind class joiner. Merges variants and resolves
+ * conflicts (e.g. `cn("p-2", "p-4")` → `"p-4"`).
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * Pick black or white text for a solid color chip.
+ *
+ * The homelab status palette forces white text on every status color
+ * EXCEPT yellow (warning: #eab308), which uses black for contrast. This
+ * helper enforces that rule wherever a user-picked color drives a chip
+ * background (TagChips, status badges, etc).
+ *
+ * The yellow rule generalizes — anything in the yellow band (high
+ * luminance + warm hue) gets black ink.
+ */
+declare function tagTextColor(hex: string): "#ffffff" | "#000000";
+
+/**
+ * Font CSS variable names used by `@jdcpuwiz/homelab-ui`'s Tailwind preset.
+ *
+ * Why constants and not re-exported loaders: Next.js's `next/font/google`
+ * is a build-time directive scanned out of your *app* source by the SWC
+ * plugin. The loader call MUST literally appear as `const X = Font(...)`
+ * in your `app/layout.tsx`; pre-bundling it through a library turns
+ * `const` into `var` and Next refuses to compile it. So the canonical
+ * setup is "paste this snippet into layout.tsx" (see README) — and these
+ * constants document the expected variable names so you wire `--font-*`
+ * correctly without guessing.
+ *
+ * Snippet to paste into `app/layout.tsx`:
+ *
+ *   import { Geist, Geist_Mono, Orbitron } from "next/font/google";
+ *
+ *   const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"] });
+ *   const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"] });
+ *   const orbitron  = Orbitron({ variable: "--font-orbitron",   subsets: ["latin"] });
+ *
+ *   <body className={`${geistSans.variable} ${geistMono.variable} ${orbitron.variable} antialiased`}>
+ *
+ * Sanity check after deploy:
+ *   getComputedStyle(document.body).fontFamily.startsWith('"Geist"')
+ */
+declare const FONT_CSS_VARIABLES: {
+    readonly sans: "--font-geist-sans";
+    readonly mono: "--font-geist-mono";
+    readonly display: "--font-orbitron";
+};
+
+export { Button, type ButtonProps, ConfirmDialog, type ConfirmDialogProps, type Crumb, EmptyState, type EmptyStateProps, FONT_CSS_VARIABLES, Modal, type ModalProps, PageHeader, type PageHeaderProps, Sidebar, SidebarNavItem, type SidebarNavItemProps, type SidebarProps, Spinner, type SpinnerProps, TagChips, type TagChipsProps, type TagRef, cn, tagTextColor };