@chesapeake/stack 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.7] - 2026-10-11
+
+### Added
+
+- Retail P0 blocks in `components/retail/`: `LocationHero`,
+  `HoursStatusStrip`, `StickyShopBar`, and `StoreSwitcher`
+- `types/retail-location.ts` — `RetailLocation` and supporting types
+  (`Address`, `WeeklyHours`, `FaqItem`, `CommercePlatform`)
+- `examples/retail-location-page.tsx` composing the P0 blocks
+- `isOpenAt` and `hoursForDay` helpers for local weekly hours
+
 ## [0.1.6] - 2026-09-19
 
 ### Added
@@ -90,8 +101,10 @@ and this project adheres to
 - Full dark mode support via CSS custom properties
 - Apache 2.0 license
 
-[0.1.4]: https://github.com/chesapeakedev/stack/releases/tag/v0.1.4
+[0.1.7]: https://github.com/chesapeakedev/stack/releases/tag/v0.1.7
 [0.1.6]: https://github.com/chesapeakedev/stack/releases/tag/v0.1.6
+[0.1.5]: https://github.com/chesapeakedev/stack/releases/tag/v0.1.5
+[0.1.4]: https://github.com/chesapeakedev/stack/releases/tag/v0.1.4
 [0.1.3]: https://github.com/chesapeakedev/stack/releases/tag/v0.1.3
 [0.1.2]: https://github.com/chesapeakedev/stack/releases/tag/v0.1.2
 [0.1.1]: https://github.com/chesapeakedev/stack/releases/tag/v0.1.1

package/README.md

@@ -335,6 +335,7 @@ installed and configured.
 | [`feedback-and-notifications.tsx`](https://github.com/chesapeakedev/stack/blob/main/examples/feedback-and-notifications.tsx) | FeedbackDrawer, toast variants (success / error / promise), confirmation Dialog |
 | [`data-display.tsx`](https://github.com/chesapeakedev/stack/blob/main/examples/data-display.tsx)                             | Cards, badges, avatars, tooltips, dropdown menus, and EmptyState                |
 | [`user-management.tsx`](https://github.com/chesapeakedev/stack/blob/main/examples/user-management.tsx)                       | UserSelector multi-select search, FriendList with presence indicators           |
+| [`retail-location-page.tsx`](https://github.com/chesapeakedev/stack/blob/main/examples/retail-location-page.tsx)         | LocationHero, HoursStatusStrip, StoreSwitcher, and StickyShopBar                |
 
 ## Package Contents
 
@@ -344,7 +345,8 @@ When installed via npm you get:
 @chesapeake/stack/
 ├── components/
 │   ├── ui/              # Primitive UI components (Button, Input, Card, …)
-│   └── ux/              # Higher-level UX components (auth, layout, feedback)
+│   ├── ux/              # Higher-level UX components (auth, layout, feedback)
+│   └── retail/          # Location page blocks (hero, hours, store switcher)
 ├── styles/
 │   ├── index.css        # Main stylesheet entry point
 │   ├── tokens.css       # Design tokens (CSS custom properties)

package/components/retail/HoursStatusStrip.tsx

@@ -0,0 +1,55 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import type { WeeklyHours } from "../../types/retail-location.ts";
+import { Badge } from "../ui/badge.tsx";
+import { cn } from "../../lib/utils.ts";
+import { hoursForDay, isOpenAt } from "./hours.ts";
+
+/**
+ * Props for {@link HoursStatusStrip}.
+ */
+export interface HoursStatusStripProps {
+  /** Weekly hours. A `null` day is closed. */
+  hours: WeeklyHours;
+  /**
+   * Instant used to decide open/closed and which day's range to show.
+   * Defaults to the current local time.
+   */
+  now?: Date;
+  /** Pre-order cutoff label, already formatted (for example `21:00`). */
+  preOrderCutoff?: string;
+  className?: string;
+}
+
+/**
+ * Open/closed badge, today's hours, and an optional pre-order cutoff.
+ *
+ * @example
+ * ```tsx
+ * <HoursStatusStrip
+ *   hours={location.hours}
+ *   preOrderCutoff={location.status?.preOrderCutoff}
+ * />
+ * ```
+ */
+export function HoursStatusStrip({
+  hours,
+  now = new Date(),
+  preOrderCutoff,
+  className,
+}: HoursStatusStripProps) {
+  const open = isOpenAt(hours, now);
+  const today = hoursForDay(hours, now);
+  const range = today ? `${today.open}–${today.close}` : "Closed today";
+
+  return (
+    <div className={cn("flex flex-wrap items-center gap-2 text-sm", className)}>
+      <Badge variant={open ? "default" : "secondary"}>
+        {open ? "Open" : "Closed"}
+      </Badge>
+      <span>{range}</span>
+      {preOrderCutoff ? <span>Order by {preOrderCutoff}</span> : null}
+    </div>
+  );
+}

package/components/retail/LocationHero.tsx

@@ -0,0 +1,64 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { Button } from "../ui/button.tsx";
+import { cn } from "../../lib/utils.ts";
+
+/**
+ * Props for {@link LocationHero}.
+ */
+export interface LocationHeroProps {
+  /** Local page headline. */
+  headline: string;
+  /** Neighborhood or district shown above the headline. */
+  neighborhood?: string;
+  /** Primary commerce action label, such as "Order pickup". */
+  primaryLabel: string;
+  /** Called when the primary commerce button is clicked. */
+  onPrimaryClick: () => void;
+  /** Secondary action label, such as "Directions". */
+  secondaryLabel: string;
+  /** Called when the directions button is clicked. */
+  onSecondaryClick: () => void;
+  className?: string;
+}
+
+/**
+ * Location headline with a primary commerce action and a directions action.
+ *
+ * @example
+ * ```tsx
+ * <LocationHero
+ *   neighborhood="Canton"
+ *   headline="Welcome to The Forest Baltimore"
+ *   primaryLabel="Order pickup"
+ *   onPrimaryClick={() => {}}
+ *   secondaryLabel="Directions"
+ *   onSecondaryClick={() => {}}
+ * />
+ * ```
+ */
+export function LocationHero({
+  headline,
+  neighborhood,
+  primaryLabel,
+  onPrimaryClick,
+  secondaryLabel,
+  onSecondaryClick,
+  className,
+}: LocationHeroProps) {
+  return (
+    <section className={cn("flex flex-col gap-4", className)}>
+      {neighborhood ? (
+        <p className="text-sm text-muted-foreground">{neighborhood}</p>
+      ) : null}
+      <h2 className="text-3xl font-bold tracking-tight">{headline}</h2>
+      <div className="flex flex-wrap gap-2">
+        <Button onClick={onPrimaryClick}>{primaryLabel}</Button>
+        <Button variant="outline" onClick={onSecondaryClick}>
+          {secondaryLabel}
+        </Button>
+      </div>
+    </section>
+  );
+}

package/components/retail/StickyShopBar.tsx

@@ -0,0 +1,44 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { Button } from "../ui/button.tsx";
+import { cn } from "../../lib/utils.ts";
+
+/**
+ * Props for {@link StickyShopBar}.
+ */
+export interface StickyShopBarProps {
+  /** Label on the persistent commerce button. */
+  label: string;
+  /** Fired when the shop button is pressed. */
+  onShopClick: () => void;
+  className?: string;
+}
+
+/**
+ * Mobile-only bar fixed to the bottom of the viewport with a commerce CTA.
+ * Hidden from the `md` breakpoint up.
+ *
+ * @example
+ * ```tsx
+ * <StickyShopBar label="Order pickup" onShopClick={() => {}} />
+ * ```
+ */
+export function StickyShopBar({
+  label,
+  onShopClick,
+  className,
+}: StickyShopBarProps) {
+  return (
+    <div
+      className={cn(
+        "fixed inset-x-0 bottom-0 z-40 border-t bg-background p-3 md:hidden",
+        className
+      )}
+    >
+      <Button className="w-full" onClick={onShopClick}>
+        {label}
+      </Button>
+    </div>
+  );
+}

package/components/retail/StoreSwitcher.tsx

@@ -0,0 +1,122 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { useEffect } from "react";
+
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "../ui/select.tsx";
+import { cn } from "../../lib/utils.ts";
+
+/** One row in {@link StoreSwitcher}. */
+export interface StoreOption {
+  slug: string;
+  name: string;
+}
+
+/**
+ * Props for {@link StoreSwitcher}.
+ *
+ * Nearest-store detection is not implemented. `RetailLocation` has no
+ * coordinates, so this control only persists an explicit choice.
+ */
+export interface StoreSwitcherProps {
+  /** Stores the shopper can choose. */
+  locations: StoreOption[];
+  /** Selected slug. Omit it to restore the last stored slug on mount. */
+  selectedSlug?: string;
+  /** Called with the slug when the shopper picks a store, or when a stored slug is restored. */
+  onSelect: (slug: string) => void;
+  /**
+   * `localStorage` key and cookie name.
+   * @default "chesapeake.retail.location"
+   */
+  storageKey?: string;
+  className?: string;
+}
+
+const DEFAULT_STORAGE_KEY = "chesapeake.retail.location";
+
+function readStoredSlug(storageKey: string): string | null {
+  try {
+    const stored = localStorage.getItem(storageKey);
+    if (stored) {
+      return stored;
+    }
+  } catch {
+    // Private mode and disabled storage still allow the in-memory selection.
+  }
+  const prefix = `${encodeURIComponent(storageKey)}=`;
+  const parts = document.cookie.split("; ");
+  for (const part of parts) {
+    if (part.startsWith(prefix)) {
+      return decodeURIComponent(part.slice(prefix.length));
+    }
+  }
+  return null;
+}
+
+function writeStoredSlug(storageKey: string, slug: string): void {
+  try {
+    localStorage.setItem(storageKey, slug);
+  } catch {
+    // Cookie write below still records the choice when storage is blocked.
+  }
+  document.cookie = `${encodeURIComponent(storageKey)}=${encodeURIComponent(slug)}; Path=/; SameSite=Lax`;
+}
+
+/**
+ * Store picker that remembers the selection in `localStorage` and a
+ * `SameSite=Lax` cookie. Use it to keep the page's shopping context on
+ * the location in the URL.
+ *
+ * @example
+ * ```tsx
+ * <StoreSwitcher
+ *   locations={[{ slug: "baltimore-md", name: "Baltimore" }]}
+ *   selectedSlug={slug}
+ *   onSelect={setSlug}
+ * />
+ * ```
+ */
+export function StoreSwitcher({
+  locations,
+  selectedSlug,
+  onSelect,
+  storageKey = DEFAULT_STORAGE_KEY,
+  className,
+}: StoreSwitcherProps) {
+  useEffect(() => {
+    if (selectedSlug) {
+      return;
+    }
+    const stored = readStoredSlug(storageKey);
+    if (stored && locations.some((location) => location.slug === stored)) {
+      onSelect(stored);
+    }
+  }, [locations, onSelect, selectedSlug, storageKey]);
+
+  const handleChange = (slug: string) => {
+    writeStoredSlug(storageKey, slug);
+    onSelect(slug);
+  };
+
+  return (
+    <Select value={selectedSlug} onValueChange={handleChange}>
+      <SelectTrigger className={cn("w-full max-w-xs", className)}>
+        <SelectValue placeholder="Choose a store" />
+      </SelectTrigger>
+      <SelectContent>
+        {locations.map((location) => (
+          <SelectItem key={location.slug} value={location.slug}>
+            {location.name}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}

package/components/retail/hours.ts

@@ -0,0 +1,56 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+  DayHours,
+  Weekday,
+  WeeklyHours,
+} from "../../types/retail-location.ts";
+
+const WEEKDAYS: readonly Weekday[] = [
+  "sun",
+  "mon",
+  "tue",
+  "wed",
+  "thu",
+  "fri",
+  "sat",
+];
+
+/** Hours for the local weekday of `at`. `null` means that day is closed. */
+export function hoursForDay(hours: WeeklyHours, at: Date): DayHours | null {
+  const key = WEEKDAYS[at.getDay()];
+  return hours[key];
+}
+
+function minutesOfDay(hhmm: string): number | null {
+  const match = /^(\d{2}):(\d{2})$/.exec(hhmm);
+  if (!match) {
+    return null;
+  }
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  if (hour > 23 || minute > 59) {
+    return null;
+  }
+  return hour * 60 + minute;
+}
+
+/**
+ * Whether `at` falls inside that local day's open range.
+ * A `null` day, an unparsable `HH:MM` value, or a time outside
+ * `[open, close)` is closed.
+ */
+export function isOpenAt(hours: WeeklyHours, at: Date): boolean {
+  const day = hoursForDay(hours, at);
+  if (!day) {
+    return false;
+  }
+  const open = minutesOfDay(day.open);
+  const close = minutesOfDay(day.close);
+  if (open === null || close === null) {
+    return false;
+  }
+  const now = at.getHours() * 60 + at.getMinutes();
+  return now >= open && now < close;
+}

package/components/retail/index.ts

@@ -0,0 +1,16 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+export { hoursForDay, isOpenAt } from "./hours.ts";
+
+export { LocationHero } from "./LocationHero.tsx";
+export type { LocationHeroProps } from "./LocationHero.tsx";
+
+export { HoursStatusStrip } from "./HoursStatusStrip.tsx";
+export type { HoursStatusStripProps } from "./HoursStatusStrip.tsx";
+
+export { StickyShopBar } from "./StickyShopBar.tsx";
+export type { StickyShopBarProps } from "./StickyShopBar.tsx";
+
+export { StoreSwitcher } from "./StoreSwitcher.tsx";
+export type { StoreOption, StoreSwitcherProps } from "./StoreSwitcher.tsx";

package/index.ts

@@ -25,6 +25,8 @@
 // Re-export everything from subdirectories for convenient imports
 export * from "./components/ui/index.ts";
 export * from "./components/ux/index.ts";
+export * from "./components/retail/index.ts";
+export * from "./types/retail-location.ts";
 export * from "./lib/utils.ts";
 export * from "./lib/githubIssue.ts";
 export { default as tailwindPreset } from "./tailwind.preset.ts";

package/lib/githubIssue.ts

@@ -112,7 +112,9 @@ export function isGitHubPullRequestPayload(value: unknown): boolean {
 }
 
 export function isValidRepoName(value: string): boolean {
-  return /^[A-Za-z0-9_.-]+$/.test(value) && value.length > 0 && value.length <= 100;
+  return (
+    /^[A-Za-z0-9_.-]+$/.test(value) && value.length > 0 && value.length <= 100
+  );
 }
 
 export function isValidIssueNumber(value: unknown): value is number {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chesapeake/stack",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "A simple, reusable React component library and design system built on shadcn/ui with Tailwind CSS",
   "type": "module",
   "packageManager": "npm@10.2.0",
@@ -78,6 +78,11 @@
     "./components/ui/textarea": "./components/ui/textarea.tsx",
     "./components/ui/tooltip": "./components/ui/tooltip.tsx",
     "./components/ux": "./components/ux/index.ts",
+    "./components/retail": "./components/retail/index.ts",
+    "./components/retail/LocationHero": "./components/retail/LocationHero.tsx",
+    "./components/retail/HoursStatusStrip": "./components/retail/HoursStatusStrip.tsx",
+    "./components/retail/StickyShopBar": "./components/retail/StickyShopBar.tsx",
+    "./components/retail/StoreSwitcher": "./components/retail/StoreSwitcher.tsx",
     "./components/ux/ActivityAnimation": "./components/ux/ActivityAnimation.tsx",
     "./components/ux/FireAnimation": "./components/ux/FireAnimation.tsx",
     "./components/ux/GifSearch": "./components/ux/GifSearch.tsx",
@@ -130,6 +135,7 @@
     "./lib/utils": "./lib/utils.ts",
     "./lib/githubIssue": "./lib/githubIssue.ts",
     "./types/user": "./types/user.ts",
+    "./types/retail-location": "./types/retail-location.ts",
     "./styles": "./styles/index.css",
     "./tailwind.preset": "./tailwind.preset.ts",
     "./eslint.config": "./eslint.config.js",

package/types/retail-location.ts

@@ -0,0 +1,73 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Canonical retail location content model.
+ *
+ * Shared with the Chesapeake audit rubric (chesapeakedev/chesapeake#485).
+ * Phase 1 deep-links into `commerce.platform`; it does not replace checkout.
+ */
+
+/** Street address for one store. */
+export interface Address {
+  street: string;
+  city: string;
+  region: string;
+  postalCode: string;
+  country: string;
+}
+
+/** Lowercase weekday key used by {@link WeeklyHours}. */
+export type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+
+/**
+ * Open and close as 24-hour local times (`HH:MM`).
+ * A closed day is `null` on {@link WeeklyHours}, not a zero-length range.
+ */
+export interface DayHours {
+  open: string;
+  close: string;
+}
+
+/** One entry per weekday. `null` means the store is closed that day. */
+export type WeeklyHours = Record<Weekday, DayHours | null>;
+
+/** One question and answer on a location page. */
+export interface FaqItem {
+  question: string;
+  answer: string;
+}
+
+/** Checkout platforms Phase 1 deep-links into. Phase 1 does not replace them. */
+export type CommercePlatform =
+  | "dutchie"
+  | "toast"
+  | "shopify"
+  | "square"
+  | "custom";
+
+/**
+ * Public facts for one retail location.
+ * `storeId` is the id the commerce platform publishes. When the page does
+ * not publish one, use a stable public slug.
+ */
+export interface RetailLocation {
+  slug: string;
+  name: string;
+  headline: string;
+  neighborhood?: string;
+  address: Address;
+  phone: string;
+  email?: string;
+  hours: WeeklyHours;
+  status?: { preOrderCutoff?: string; badge?: string };
+  commerce: {
+    platform: CommercePlatform;
+    storeId: string;
+    shopUrl: string;
+    categoryLinks?: Record<string, string>;
+  };
+  faqs: FaqItem[];
+  localSeo?: { landmarks: string[]; serviceAreas: string[]; guide: string };
+  social?: { googlePlaceId?: string };
+}