@chesapeake/stack 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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.0] - 2026-02-05
+
+### Added
+
+- Initial public release
+- shadcn/ui based component library with New York style
+- UI components: Button, Avatar, Calendar, Card, Dialog, Drawer, DropdownMenu,
+  Input, Label, Textarea, Checkbox, Popover, Select, Separator, Sonner, Tooltip,
+  Badge, ButtonGroup
+- UX components: UserSearch, UserSelector, FriendList, FriendRequestList,
+  GifSearch, ImageUpload, TutorialCarousel, PageLayout, FeedbackDrawer,
+  ThemeProvider
+- Authentication components: GoogleAuth, GitHubAuth with providers and callbacks
+- Tailwind CSS preset with design tokens
+- Full dark mode support via CSS custom properties
+- Apache 2.0 license
+
+[0.1.0]: https://github.com/chesapeake-computing/stack/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Chesapeake Computing
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,440 @@
+# @chesapeake/stack
+
+<!-- npm badge: uncomment when published to npm
+[![npm version](https://badge.fury.io/js/@chesapeake/stack.svg)](https://www.npmjs.com/package/@chesapeake/stack)
+-->
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+A reusable React component library and design system built on shadcn components
+& derived user experiences. the shadcn community seems to refer to these things
+as blocks, which we currently don't support. The npm package contains a tiny
+design system in the form of a tailwind preset & a single css import. The design
+system consists of:
+
+- Reusable React components in `components/` (UI components in `ui/`, UX
+  components in `ux/`)
+- `styles/index.css` that includes Tailwind CSS, design tokens, base styles, and
+  component styles
+- `tailwind.preset.ts` for use in `tailwind.config.ts`
+- Peer dependencies declared for any component dependencies
+
+## Installation
+
+To utilize the design system in your app:
+
+### 1. Install Dependencies
+
+Add the required peer dependencies to your app's `package.json`:
+
+```bash
+npm install react react-dom tailwindcss tw-animate-css
+npm install react-day-picker vaul  # if using calendar or drawer components
+```
+
+### 2. Import Styles
+
+Import the shared styles in your app's main CSS file (e.g., `src/index.css`):
+
+```css
+/* Import Tailwind, third-party CSS, and shared styles */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "react-day-picker/style.css"; /* if using calendar component */
+@import "vaul/style.css"; /* if using drawer component */
+@import "@chesapeake/stack/styles/index.css";
+```
+
+### 3. Configure Bundler and TypeScript
+
+If you consume the package from source (e.g. in a monorepo), add a path alias so
+imports resolve correctly. When using the published npm package, use the package
+name in place of `@chesapeake/stack` in the examples below.
+
+**Vite** (`vite.config.ts`):
+
+```typescript
+import path from "path";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "@shared": path.resolve(__dirname, "../stack"),
+    },
+  },
+});
+```
+
+**TypeScript** (`tsconfig.json`):
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@shared/*": ["../stack/*"]
+    }
+  }
+}
+```
+
+### 4. Configure Tailwind
+
+Extend your `tailwind.config.ts` with the shared preset:
+
+```typescript
+import type { Config } from "tailwindcss";
+import sharedPreset from "@chesapeake/stack/tailwind.preset";
+
+const config: Config = {
+  content: [
+    // your app's content paths
+  ],
+  presets: [sharedPreset],
+  // your app's additional configuration
+};
+
+export default config;
+```
+
+### 5. Configure Tailwind Content
+
+Add the package to your Tailwind content configuration so classes are processed:
+
+**`tailwind.config.ts`**:
+
+```typescript
+import type { Config } from "tailwindcss";
+import sharedPreset from "@chesapeake/stack/tailwind.preset";
+
+const config: Config = {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./node_modules/@chesapeake/stack/**/*.{js,ts,jsx,tsx}",
+  ],
+  presets: [sharedPreset],
+  // your app's additional configuration
+};
+
+export default config;
+```
+
+### 6. Import and Use Components
+
+Import and use components in your React components:
+
+```tsx
+import { Button } from "@chesapeake/stack/components/ui/button";
+import { ThemeProvider } from "@chesapeake/stack/components/ux/theme-provider";
+
+function App() {
+  return (
+    <ThemeProvider>
+      <Button variant="default">Click me</Button>
+    </ThemeProvider>
+  );
+}
+```
+
+### Why peer dependencies?
+
+The package declares peer dependencies instead of bundling them so that:
+
+- **CSS is correct**: Third-party CSS (Tailwind, react-day-picker, vaul, etc.)
+  is imported once in your app instead of via the package.
+- **Versions stay flexible**: Your app installs and controls the versions that
+  work with your build.
+- **Bundle size stays small**: No duplicated CSS or runtime deps inside the
+  package.
+
+Install the peer dependencies listed in the package’s `package.json` in your
+app.
+
+### Installation troubleshooting
+
+- **CSS not loading**: Ensure all peer dependencies are installed, CSS imports
+  are in your main CSS file in the right order, and your bundler/TypeScript path
+  mapping resolves `@chesapeake/stack` (or the package name) correctly.
+- **Version conflicts**: Use `npm ls` to inspect installed versions; align with
+  the peer dependency ranges required by the package.
+- **Build errors**: Run the package’s validate script (e.g. `make validate`) if
+  available, confirm required CSS files exist, and check import paths.
+
+### Types (optional)
+
+The package exports shared TypeScript types for use in consuming apps (e.g. user
+and friend types). Import from the `types/user` subpath:
+
+```ts
+import type {
+  BaseUser,
+  Friend,
+  toBaseUser,
+} from "@chesapeake/stack/types/user";
+```
+
+### Migrating from an older setup
+
+If you previously copied shared CSS or used a different import pattern: remove
+duplicate CSS, switch to the import pattern above, install any missing peer
+dependencies, and test all components.
+
+## Usage
+
+### Available Components
+
+#### UI Components (`components/ui/`)
+
+- **Button** - Various button variants and sizes
+- **Input** - Form input component
+- **Label** - Form label component
+- **Textarea** - Multi-line text input
+- **Avatar** - User avatar display
+- **Calendar** - Date picker component
+- **Drawer** - Slide-out drawer component
+- **Dropdown Menu** - Dropdown menu component
+- **Location Input** - Location search input
+- **Popover** - Popover component
+- **Toast** - Toast notification system
+
+#### UX Components (`components/ux/`)
+
+- **Theme Provider** - Dark/light theme context provider
+- **Gif Search** - GIF search and selection component
+- **Image Upload** - Image upload component
+- **Tutorial Carousel** - Step-by-step tutorial component
+- **Page Layout** - `PageContent`, `PageHeader`, `PageLayout` for consistent
+  page structure
+
+### Design System Features
+
+- **Design Tokens**: Consistent color palette, spacing, and typography
+- **Dark Mode**: Built-in dark theme support
+- **Responsive**: Mobile-first responsive design
+- **Accessibility**: ARIA-compliant components
+- **Animations**: Smooth transitions and micro-interactions
+
+## Theming
+
+This section explains how the shared theme system works and how projects can
+customize themes.
+
+### Base Theme
+
+The shared design system (`@chesapeake/stack`) includes a default theme defined
+in `stack/styles/tokens.css`. This theme includes:
+
+- **Color palette**: Primary, secondary, muted, accent, destructive colors
+- **Light and dark mode**: Automatic theme switching via `.dark` class
+- **Typography**: Poppins (sans-serif), Lora (serif), Fira Code (monospace)
+- **Shadows**: Custom shadow system with offset shadows
+- **Border radius**: Consistent radius values
+- **Chart colors**: Pre-defined chart color palette
+
+This theme is automatically applied to any project that imports
+`@chesapeake/stack/styles/index.css`.
+
+### Using the Default Theme
+
+Projects use the default theme automatically:
+
+```css
+/* e.g. src/index.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "react-day-picker/style.css";
+@import "@chesapeake/stack/styles/index.css";
+/* That's it! Default theme is now active */
+```
+
+**Don't forget to load fonts in your `index.html`:**
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&family=Lora:wght@400;500;600&family=Fira+Code:wght@400;500;600&display=swap"
+  rel="stylesheet"
+/>
+```
+
+### Overriding the Theme
+
+Projects can override specific theme variables to create a different look and
+feel:
+
+```css
+/* e.g. src/index.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "react-day-picker/style.css";
+@import "@chesapeake/stack/styles/index.css";
+
+/* Override theme variables */
+:root {
+  /* Change primary color */
+  --primary: oklch(0.723 0.219 149.579);
+
+  /* Change background */
+  --background: oklch(0.95 0.01 200);
+
+  /* Use different fonts */
+  --font-sans: "Inter", sans-serif;
+  --font-serif: "Crimson Text", serif;
+  --font-mono: "JetBrains Mono", monospace;
+}
+
+.dark {
+  /* Override dark mode colors */
+  --primary: oklch(0.8 0.2 150);
+  --background: oklch(0.2 0.02 200);
+}
+
+/* Project-specific utility classes (e.g. brand gradient) */
+.my-brand-gradient {
+  background: linear-gradient(to right, var(--primary), var(--secondary));
+}
+```
+
+### CSS Variable Priority
+
+CSS custom properties follow standard CSS cascade rules:
+
+1. **Shared theme** (`@chesapeake/stack/styles/tokens.css`) - Base defaults
+2. **Project overrides** (your `index.css` after
+   `@import "@chesapeake/stack/styles/index.css"`) - Your customizations
+3. **Inline styles** (component-level) - Most specific
+
+This means you only need to override the variables you want to change!
+
+### Available Theme Variables
+
+#### Colors
+
+- `--background`, `--foreground`
+- `--primary`, `--primary-foreground`
+- `--secondary`, `--secondary-foreground`
+- `--muted`, `--muted-foreground`
+- `--accent`, `--accent-foreground`
+- `--destructive`, `--destructive-foreground`
+- `--card`, `--card-foreground`
+- `--popover`, `--popover-foreground`
+- `--border`, `--input`, `--ring`
+- `--chart-1` through `--chart-5`
+- `--sidebar-*` variants
+
+#### Typography
+
+- `--font-sans` (default: Poppins)
+- `--font-serif` (default: Lora)
+- `--font-mono` (default: Fira Code)
+
+#### Spacing & Layout
+
+- `--radius` (default: 0.4rem)
+- `--spacing` (default: 0.25rem)
+- `--tracking-normal` (default: 0em)
+
+#### Shadows
+
+- `--shadow-2xs`, `--shadow-xs`, `--shadow-sm`, `--shadow`, `--shadow-md`,
+  `--shadow-lg`, `--shadow-xl`, `--shadow-2xl`
+- `--shadow-x`, `--shadow-y`, `--shadow-blur`, `--shadow-spread`,
+  `--shadow-opacity`, `--shadow-color`
+
+### Example: Creating a Custom Brand Theme
+
+```css
+/* e.g. src/index.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@chesapeake/stack/styles/index.css";
+
+:root {
+  /* Brand colors */
+  --primary: oklch(0.65 0.25 250); /* Purple brand */
+  --secondary: oklch(0.75 0.15 180); /* Teal accent */
+  --accent: oklch(0.85 0.1 300); /* Pink accent */
+
+  /* Custom background */
+  --background: oklch(0.98 0.005 260); /* Very light purple tint */
+
+  /* Custom fonts */
+  --font-sans: "Inter", "system-ui", sans-serif;
+  --font-serif: "Crimson Text", serif;
+  --font-mono: "SF Mono", "Monaco", monospace;
+
+  /* Larger border radius for softer look */
+  --radius: 0.75rem;
+}
+
+.dark {
+  /* Dark mode adjustments */
+  --primary: oklch(0.75 0.25 250);
+  --background: oklch(0.15 0.02 260);
+  --secondary: oklch(0.65 0.15 180);
+}
+
+/* Custom utility classes for this app */
+.my-app-gradient {
+  background: linear-gradient(135deg, var(--primary), var(--secondary));
+}
+```
+
+### Theming Tips
+
+1. **Always import shared styles first**, then override
+2. **Use OKLCH color space** for better color interpolation and consistency
+3. **Test both light and dark modes** when customizing
+4. **Keep shadow values** unless you want a completely different shadow system
+5. **Override fonts** if your brand requires different typography
+6. **Use Tailwind's color utilities** - they automatically use your custom
+   variables
+
+### Migrating from an Older Theme
+
+If you're migrating from the old theme:
+
+1. Check which variables your project currently uses
+2. Import `@chesapeake/stack/styles/index.css`
+3. Override only the variables that need to change
+4. Test thoroughly in both light and dark modes
+
+### Further Reading
+
+- [MDN: CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) -
+  Comprehensive guide with examples
+- [CSS Tricks: Custom Properties](https://css-tricks.com/a-complete-guide-to-custom-properties/) -
+  In-depth tutorial and best practices
+- [Can I Use: CSS Custom Properties](https://caniuse.com/css-variables) -
+  Browser support information
+
+## Project Structure
+
+```
+stack/
+├── components/
+│   ├── ui/           # Basic UI components (shadcn/ui primitives)
+│   └── ux/           # Complex UX components (auth, layout, feedback)
+├── styles/
+│   ├── index.css     # Main stylesheet entry point
+│   ├── tokens.css    # Design tokens and CSS variables
+│   ├── base.css      # Base styles and utilities
+│   └── components.css # Component-specific styles
+├── lib/
+│   └── utils.ts      # Utility functions
+├── types/            # Shared TypeScript types (e.g. user)
+├── tailwind.preset.ts # Tailwind configuration preset
+├── index.html        # Demo app entry (run npm run dev to preview)
+├── src/              # Demo app source (showcase components)
+├── public/           # Demo app static assets
+├── Makefile          # Lint, validate, add_component
+└── package.json      # Package configuration and exports
+```
+
+The demo app (`index.html`, `src/`, `public/`) is for local development and
+showcase only; it is not published to npm.
+
+# Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, adding shadcn
+components, and opening PRs.