showcase-hero

A polished, data-driven React hero component for presenting selected work, products, case studies, writing, demos, or technical references.

@petesmithofficial/showcase-hero exports a typed ShowcaseHero component with a responsive layout, optional action links, floating orbit labels, and an interactive workbench for highlighting selected items.

npm package

Features

• Typed React API with first-class TypeScript declarations.
• Data-driven content model for hero copy, calls to action, orbit labels, and selected work.
• Interactive workbench with pointer tracking, keyboard navigation, hover previews, and touch support.
• Configurable workbench tilt and touch release behavior through workbench.motion.
• Scoped stylesheet with responsive layout and reduced-motion handling.
• Packaged for normal npm installation with CSS and documentation assets included.

Release Notes

Current release: 0.2.0.

• Added workbench.motion.touchReleaseReturn for tuning touch release hold and return timing.
• Pointer tracking is smoothed across mouse and touch input so the workbench follows movement fluidly without losing its responsive feel.
• Added inline TypeScript documentation for exported prop types, improving editor hover and autocomplete guidance.
• No breaking changes from 0.1.x.

See CHANGELOG.md for full release notes.

Install

npm install @petesmithofficial/showcase-hero

Quick Start

Import the component and stylesheet from the package:

import { ShowcaseHero, type ShowcaseHeroProps } from "@petesmithofficial/showcase-hero";
import "@petesmithofficial/showcase-hero/styles.css";

const hero: ShowcaseHeroProps = {
  actions: [
    { href: "#work", label: "View work" },
    { href: "/contact", label: "Contact", variant: "secondary" },
  ],
  content: {
    detail: "A focused introduction for selected work, product stories, and technical notes.",
    eyebrow: "Portfolio system",
    name: "Showcase Hero",
    statement: "A flexible hero for public work.",
  },
  orbitTiles: [{ label: "UI" }, { label: "API" }, { label: "DOC" }],
  workbench: {
    caption: "One hero. Any curated set of work.",
    id: "work",
    items: [
      {
        destination: {
          href: "https://example.com/case-study",
          label: "Open case study ->",
          rel: "noopener noreferrer",
          target: "_blank",
          type: "case study",
        },
        details: [
          { label: "Context", value: "Launch story for a focused product workflow." },
          { label: "Format", value: "Outcome, screenshots, technical notes, and next steps." },
        ],
        metadata: ["product", "case study"],
        name: "Launch Brief",
        signal: "case study",
        slug: "launch-brief",
        summary: "product launch story",
      },
    ],
    listLabel: "Selectable showcase items",
    motion: { maxTiltDegrees: 12 },
    selectedLabel: "selected item",
    tags: ["typed props", "responsive", "themeable"],
    title: "selected work",
  },
};

export function Page() {
  return <ShowcaseHero {...hero} />;
}

API

ShowcaseHero accepts a single ShowcaseHeroProps object.

| Prop | Type | Description | | --- | --- | --- | | content | ShowcaseHeroContent | Required hero copy: eyebrow, name, statement, and detail. | | actions | ShowcaseHeroAction[] | Optional primary and secondary links displayed below the hero copy. | | orbitTiles | ShowcaseHeroOrbitTile[] | Optional floating labels. The first four tiles receive default positions. | | workbench | ShowcaseHeroWorkbench | Optional interactive panel for selectable showcase items. | | className | string | Optional class added to the root section. | | id | string | Optional root section id. | | titleId | string | Optional id for the hero heading used by aria-labelledby. |

Workbench Items

Each workbench item is intentionally neutral, so it can represent a case study, project, article, demo, download, product area, or reference.

| Field | Description | | --- | --- | | name | Visible item title. | | summary | Short row description. | | signal | Compact category or status label. | | slug | Stable caller-owned identifier. | | details | Optional label/value rows for the selected item panel. | | metadata | Optional chips such as technology, medium, status, or audience. | | destination | Optional link with caller-controlled label, target, rel, aria label, and type. |

Motion

The workbench follows the pointer using viewport-based rotation and subtle translation. By default, the maximum Y-axis tilt is 8deg. On touch devices, the workbench holds the final touch tilt for 220ms, then eases back to its idle centered pose over 760ms.

Pointer tracking is smoothed across coarse touch event streams while remaining direct enough for desktop pointer movement. This smoothing is part of the component behavior; consumers normally only need to tune the amplitude and touch release timing below.

Use workbench.motion.maxTiltDegrees to tune the rotation intensity. A value around 12 gives a stronger, more responsive follow effect; lower values such as 5 or 6 are calmer.

const hero: ShowcaseHeroProps = {
  content,
  workbench: {
    caption: "Selected work",
    items,
    motion: { maxTiltDegrees: 5 },
    title: "workbench",
  },
};

Use workbench.motion.touchReleaseReturn to tune the mobile touch release behavior. Both values are optional; omitted or invalid values fall back to the defaults.

const hero: ShowcaseHeroProps = {
  content,
  workbench: {
    caption: "Selected work",
    items,
    motion: {
      maxTiltDegrees: 12,
      touchReleaseReturn: {
        holdMs: 220,
        durationMs: 760,
      },
    },
    title: "workbench",
  },
};

| Motion field | Default | Description | | --- | --- | --- | | maxTiltDegrees | 8 | Maximum Y-axis tilt used to scale pointer-follow rotation. | | touchReleaseReturn.holdMs | 220 | Touch release return hold time before the workbench starts returning. | | touchReleaseReturn.durationMs | 760 | How long the touch release return animation takes. |

The package owns the motion transform and hit-tested workbench layout. Consumer styles should not apply transforms, pointer-event changes, overflow changes, or z-index changes to internal motion classes such as .hero-art-stage, .hero-art-motion-layer, .workbench-list, or .workbench-row; those overrides can make visible rows drift away from their click targets. Prefer the root className prop and CSS custom properties for theming.

The hero title is ordinary caller-provided text. Natural word breaks, such as Showcase Hero, produce cleaner mobile wrapping than long unbroken names such as ShowcaseHero; the stylesheet still includes emergency wrapping so narrow screens do not overflow.

Styling

Import the packaged stylesheet once in your app:

import "@petesmithofficial/showcase-hero/styles.css";

The stylesheet is scoped under .showcase-hero. Import it once and let it own the component structure, motion wrappers, list behavior, and responsive layout. You can override colors, spacing, shadows, and panel treatments with CSS custom properties on the component root:

.showcase-hero {
  --bg: #111318;
  --panel: rgba(255, 255, 255, 0.08);
  --text: #f5f1e8;
  --muted: #a8adbb;
  --line: rgba(255, 255, 255, 0.13);
  --accent: #f4c95d;
  --accent-electric: #f4c95d;
  --accent-cyan: #63f7ff;
  --shadow: 0 28px 90px rgba(0, 0, 0, 0.45);
  --radius: 8px;
}

If you need heavier visual customization, add a caller-owned class with className and keep overrides focused on color, font, shadow, border, and background properties. Avoid replacing the internal layout and interaction rules unless you are intentionally forking the component.

Accessibility

• The root section uses aria-labelledby for the hero heading.
• The workbench list supports pointer selection and keyboard navigation with ArrowUp, ArrowDown, Home, and End.
• Destination links accept caller-provided ariaLabel, target, and rel values.
• Motion is disabled for users who request reduced motion.

Development

make dev
make verify

The local demo runs on http://localhost:8788.

make verify runs TypeScript checks, the production build, and package contract checks.

License

MIT. See LICENSE.