@chesapeake/stack 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -6,6 +6,26 @@ 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.8] - 2026-11-08
+
+### Added
+
+- `lib/layoutTier`, `lib/useMediaQuery`, `lib/useLayoutTier`: compact /
+  hybrid / comfortable viewport tiers (Tailwind-aligned breakpoints)
+- `StandardLayout` sets `data-layout-tier` and slightly tighter shell padding on
+  small viewports
+
+## [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 +110,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

@@ -17,6 +17,10 @@ system consists of:
 - `styles/index.css` that includes Tailwind CSS, design tokens, base styles, and
   component styles
 - `tailwind.preset.ts` for use in `tailwind.config.ts`
+- **Layout tiers** (`compact` / `hybrid` / `comfortable`): `useLayoutTier`,
+  `LAYOUT_TIER_*` constants, and `data-layout-tier` on `StandardLayout`. See
+  denoise-ui `docs/responsive-layout.md` for product rules; apps own feature
+  toolbars.
 
 ## Installation
 
@@ -335,6 +339,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 +349,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/components/ux/StandardLayout/StandardLayout.tsx

@@ -5,6 +5,7 @@
 import { useState } from "react";
 import { Button } from "../../../components/ui/button";
 import { useAuth } from "../auth";
+import { useLayoutTier } from "../../../lib/useLayoutTier.ts";
 import { ProfilePage } from "./ProfilePage";
 import type { AuthUser } from "../auth/context";
 
@@ -46,6 +47,8 @@ export function StandardLayout({
   maxWidth,
 }: StandardLayoutProps) {
   const [showProfile, setShowProfile] = useState(false);
+  const layoutTier = useLayoutTier();
+  const shellPadding = "p-3 md:p-4";
   const { user: authUser } = useAuth();
 
   // Determine if user is logged in based on authUser
@@ -94,11 +97,14 @@ export function StandardLayout({
     return (
       <div
         className={`h-screen flex flex-col overflow-hidden ${className ?? ""}`}
+        data-layout-tier={layoutTier}
       >
         {/* Toolbar/Header */}
         <div className="border-b bg-background flex-shrink-0">
           <div className="flex justify-center">
-            <div className={`w-full ${getMaxWidthClass(maxWidth)} p-4`}>
+            <div
+              className={`w-full ${getMaxWidthClass(maxWidth)} ${shellPadding}`}
+            >
               <div className="flex justify-between items-center">
                 {headerContent ? (
                   <div className="flex items-center gap-2 w-full">
@@ -242,11 +248,14 @@ export function StandardLayout({
   return (
     <div
       className={`h-screen flex flex-col overflow-hidden ${className ?? ""}`}
+      data-layout-tier={layoutTier}
     >
       {/* Toolbar/Header */}
       <div className="border-b bg-background flex-shrink-0">
         <div className="flex justify-center">
-          <div className={`w-full ${getMaxWidthClass(maxWidth)} p-4`}>
+          <div
+            className={`w-full ${getMaxWidthClass(maxWidth)} ${shellPadding}`}
+          >
             <div className="flex justify-between items-center">
               {headerContent ? (
                 <div className="flex items-center gap-2 w-full">

package/components/ux/StandardLayout/index.ts

@@ -14,6 +14,20 @@ export {
   PageHeader,
   PageLayout,
 } from "./PageLayout.tsx";
+
+export {
+  LAYOUT_TIER_COMPACT_MAX_PX,
+  LAYOUT_TIER_COMFORTABLE_MIN_PX,
+  LAYOUT_TIER_DIALOG_MIN_MEDIA,
+  LAYOUT_TIER_MEDIA,
+  resolveLayoutTier,
+  type LayoutTier,
+} from "../../../lib/layoutTier.ts";
+export {
+  useLayoutTier,
+  useLayoutTierWidth,
+} from "../../../lib/useLayoutTier.ts";
+export { useMediaQuery } from "../../../lib/useMediaQuery.ts";
 export type {
   PageContainerProps,
   PageContentProps,

package/components/ux/runner/RunnerStatusCard.tsx

@@ -1,23 +1,52 @@
 import type { ReactNode } from "react";
 import { Card } from "../../ui/card.tsx";
 
+/** Per-checkout readiness reported by the paired runner. */
+export interface RepositoryReadinessEntry {
+  repository: string;
+  ready: boolean;
+  reason?: string;
+}
+
 export interface RunnerStatusCardProps {
   name: string;
   state: string;
   details?: string;
   repositories?: string[];
+  /** Slug highlighted as the kickstart target for this page. */
+  targetRepository?: string;
+  /** Optional readiness per registered slug. */
+  repositoryReadiness?: RepositoryReadinessEntry[];
   children?: ReactNode;
   jobs?: ReactNode;
 }
 
+function readinessForSlug(
+  slug: string,
+  entries: RepositoryReadinessEntry[] | undefined
+): RepositoryReadinessEntry | undefined {
+  if (!entries?.length) return undefined;
+  const lower = slug.toLowerCase();
+  return entries.find((entry) => entry.repository.toLowerCase() === lower);
+}
+
 export function RunnerStatusCard({
   name,
   state,
   details,
   repositories = [],
+  targetRepository,
+  repositoryReadiness,
   children,
   jobs,
 }: RunnerStatusCardProps) {
+  const targetLower = targetRepository?.trim().toLowerCase();
+  const slugs = repositories.length
+    ? repositories
+    : targetRepository
+      ? [targetRepository]
+      : [];
+
   return (
     <Card
       className="space-y-3 rounded-md border p-4"
@@ -39,11 +68,35 @@ export function RunnerStatusCard({
       </div>
       <div>
         <p className="text-sm font-medium">Repository access</p>
-        {repositories.length ? (
+        {slugs.length ? (
           <ul className="text-muted-foreground mt-1 list-inside list-disc text-sm">
-            {repositories.map((repository) => (
-              <li key={repository}>{repository}</li>
-            ))}
+            {slugs.map((repository) => {
+              const readiness = readinessForSlug(
+                repository,
+                repositoryReadiness
+              );
+              const isTarget =
+                targetLower != null && repository.toLowerCase() === targetLower;
+              return (
+                <li
+                  key={repository}
+                  className={
+                    isTarget ? "text-foreground font-medium" : undefined
+                  }
+                  title={readiness?.reason}
+                >
+                  {repository}
+                  {isTarget ? " · kickstart target" : ""}
+                  {readiness != null
+                    ? readiness.ready
+                      ? " · ready"
+                      : ` · not ready${
+                          readiness.reason ? `: ${readiness.reason}` : ""
+                        }`
+                    : ""}
+                </li>
+              );
+            })}
           </ul>
         ) : (
           <p className="text-muted-foreground mt-1 text-sm">

package/index.ts

@@ -25,6 +25,11 @@
 // 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 * from "./lib/layoutTier.ts";
+export * from "./lib/useMediaQuery.ts";
+export * from "./lib/useLayoutTier.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/lib/layoutTier.test.ts

@@ -0,0 +1,16 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { resolveLayoutTier } from "./layoutTier.ts";
+
+await test("resolveLayoutTier boundaries", () => {
+  assert.equal(resolveLayoutTier(390), "compact");
+  assert.equal(resolveLayoutTier(767), "compact");
+  assert.equal(resolveLayoutTier(768), "hybrid");
+  assert.equal(resolveLayoutTier(683), "compact");
+  assert.equal(resolveLayoutTier(1023), "hybrid");
+  assert.equal(resolveLayoutTier(1024), "comfortable");
+  assert.equal(resolveLayoutTier(1920), "comfortable");
+});

package/lib/layoutTier.ts

@@ -0,0 +1,26 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/** Three-tier layout names aligned with Tailwind default breakpoints. */
+export type LayoutTier = "compact" | "hybrid" | "comfortable";
+
+/** Max width (px) for compact tier (below md). */
+export const LAYOUT_TIER_COMPACT_MAX_PX = 767;
+
+/** Min width (px) for comfortable tier (lg and up). */
+export const LAYOUT_TIER_COMFORTABLE_MIN_PX = 1024;
+
+export const LAYOUT_TIER_MEDIA = {
+  compact: `(max-width: ${String(LAYOUT_TIER_COMPACT_MAX_PX)}px)`,
+  hybrid: `(min-width: 768px) and (max-width: ${String(LAYOUT_TIER_COMFORTABLE_MIN_PX - 1)}px)`,
+  comfortable: `(min-width: ${String(LAYOUT_TIER_COMFORTABLE_MIN_PX)}px)`,
+} as const;
+
+/** Dialog vs drawer: at md and above use dialog shell. */
+export const LAYOUT_TIER_DIALOG_MIN_MEDIA = "(min-width: 768px)";
+
+export function resolveLayoutTier(viewportWidthPx: number): LayoutTier {
+  if (viewportWidthPx <= LAYOUT_TIER_COMPACT_MAX_PX) return "compact";
+  if (viewportWidthPx < LAYOUT_TIER_COMFORTABLE_MIN_PX) return "hybrid";
+  return "comfortable";
+}

package/lib/useLayoutTier.ts

@@ -0,0 +1,32 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/** @jsxImportSource react */
+import {
+  LAYOUT_TIER_MEDIA,
+  type LayoutTier,
+  resolveLayoutTier,
+} from "./layoutTier.ts";
+import { useMediaQuery } from "./useMediaQuery.ts";
+import { useMemo } from "react";
+
+/**
+ * Current viewport layout tier (compact / hybrid / comfortable).
+ */
+export function useLayoutTier(): LayoutTier {
+  const compact = useMediaQuery(LAYOUT_TIER_MEDIA.compact);
+  const comfortable = useMediaQuery(LAYOUT_TIER_MEDIA.comfortable);
+
+  return useMemo(() => {
+    if (compact) return "compact";
+    if (comfortable) return "comfortable";
+    return "hybrid";
+  }, [compact, comfortable]);
+}
+
+export function useLayoutTierWidth(): number {
+  if (typeof window === "undefined") return 1280;
+  return window.innerWidth;
+}
+
+export { resolveLayoutTier };

package/lib/useMediaQuery.ts

@@ -0,0 +1,29 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/** @jsxImportSource react */
+import { useEffect, useState } from "react";
+
+/**
+ * Subscribe to a CSS media query; returns whether it currently matches.
+ */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(() => {
+    if (typeof window === "undefined") return false;
+    return window.matchMedia(query).matches;
+  });
+
+  useEffect(() => {
+    const media = window.matchMedia(query);
+    const onChange = () => {
+      setMatches(media.matches);
+    };
+    onChange();
+    media.addEventListener("change", onChange);
+    return () => {
+      media.removeEventListener("change", onChange);
+    };
+  }, [query]);
+
+  return matches;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chesapeake/stack",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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",
@@ -129,7 +134,11 @@
     "./components/ux/auth/github/types": "./components/ux/auth/github/types.ts",
     "./lib/utils": "./lib/utils.ts",
     "./lib/githubIssue": "./lib/githubIssue.ts",
+    "./lib/layoutTier": "./lib/layoutTier.ts",
+    "./lib/useMediaQuery": "./lib/useMediaQuery.ts",
+    "./lib/useLayoutTier": "./lib/useLayoutTier.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 };
+}